Skip to Content
Agents & APIAPI reference

A complete reference for the derived API. Every path below is relative to the base URL:

https://derived.pro/api/cli

Send your key as a bearer token on every request (Authorization: Bearer …). The Permission column shows the key permission the endpoint requires: 👁️ Read, ✏️ Write, or 🪄 Generate. Permissions are explained in Use the API directly and Create an API key.

All responses are JSON. Every error has one shape, { "error": { "code", "message" } }, with an HTTP status that matches the code. See Errors at the bottom.

Discovery

MethodPathPermission
GET/none

The root of the API describes itself: the scope vocabulary, the auth scheme, a sample endpoint list, and where a person gets a key. It never returns a 401. A missing, malformed, or revoked key gets a 200 with the anonymous document and a caller.reason saying which. A valid key adds one caller block and unlocks nothing else.

curl "https://derived.pro/api/cli"

Account

MethodPathPermission
GET/account👁️ Read

Returns your workspace’s name and current unit balance:

curl "https://derived.pro/api/cli/account" \
-H "Authorization: Bearer paste-your-key-here"
{ "account": { "organisationId": "...", "name": "My Workspace", "units": 200 } }

Projects

MethodPathPermissionNotes
GET/projects👁️ ReadList projects. Add ?include_archived=true to include archived ones.
POST/projects✏️ WriteCreate a project (and a starter canvas). Body: { name? }.
PATCH/projects/{projectId}✏️ WriteRename a project. Body: { name }.
GET/projects/{projectId}/canvases👁️ ReadList canvases in a project.
curl -X POST "https://derived.pro/api/cli/projects" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Spring Campaign" }'

Canvases

MethodPathPermissionNotes
GET/canvases👁️ ReadList canvases. Paginated: limit (1–100, default 20), offset. The response carries pagination.hasMore.
POST/canvases✏️ WriteCreate a canvas. Body: { name, projectId } (both required).
GET/canvases/{canvasId}/state👁️ ReadCanvas state: objects, viewport, summary. Paginated: view (thin/full), limit (1–500), cursor, type.
PATCH/canvases/{canvasId}✏️ WriteUpdate name, coverImageUrl, or projectId.
DELETE/canvases/{canvasId}✏️ WriteDelete the canvas and its objects.
POST/canvases/{canvasId}/duplicate✏️ WriteClone the canvas and all objects. Body: { name? }.
PATCH/canvases/{canvasId}/viewport✏️ WriteSet zoom (0.05–20), panX, panY.
curl "https://derived.pro/api/cli/canvases/<canvasId>/state" \
-H "Authorization: Bearer paste-your-key-here"

Objects

Object creation has one endpoint per type. There is no generic create endpoint. Image and video objects are also created by generation.

MethodPathPermissionNotes
GET/canvases/{canvasId}/objects?ids=…👁️ ReadFull detail for up to 25 object ids. Unknown ids are returned in notFound.
PATCH/canvases/{canvasId}/objects/metadata✏️ WriteBulk tags for up to 100 objects in one call. Full replace. Partial failure is a 200 with per-id results.
POST/canvases/{canvasId}/objects/image✏️ WriteUpload from imageUrl or imageBase64 (+mimeType). Optional left, top, tags. Max 10 MB.
POST/canvases/{canvasId}/objects/text✏️ WriteBody: { content, x?, y?, width?, height?, fontSize?, fontFamily?, color? }.
POST/canvases/{canvasId}/objects/prompt✏️ WriteBody: { content, x?, y?, width?, height? }. Supports <var> and {SmartRef} tokens.
POST/canvases/{canvasId}/objects/variable✏️ WriteBody: { name, value, x?, y?, width?, height? }.
PATCH/canvases/{canvasId}/objects/{objectId}/position✏️ WriteMove/resize: any of x, y, width, height.
PATCH/canvases/{canvasId}/objects/{objectId}/text✏️ WriteUpdate text content.
PATCH/canvases/{canvasId}/objects/{objectId}/prompt✏️ WriteUpdate content. Optional expected_version.
PATCH/canvases/{canvasId}/objects/{objectId}/variable✏️ WriteUpdate name and/or value. Optional expected_version.
PATCH/canvases/{canvasId}/objects/{objectId}/metadata✏️ WriteImage only: update displayName and/or tags.
PATCH/canvases/{canvasId}/objects/{objectId}/crop✏️ WriteSet a 0–1 crop, or { clear: true } to remove it.
POST/canvases/{canvasId}/objects/{objectId}/duplicate✏️ WriteCopy an object on the same canvas (+20px offset).
POST/canvases/{canvasId}/objects/{objectId}/extract-frame✏️ WriteExtract a still frame from a video object.
DELETE/canvases/{canvasId}/objects✏️ WriteBatch delete, up to 100 ids. Body: { objectIds: [...] }. Unknown ids are skipped. Library images are not deleted.
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/objects/text" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "content": "Hello", "x": 0, "y": 0, "fontSize": 24, "color": "#FFFFFF" }'

See Canvases & objects for the full walkthrough and the note on center-origin coordinates.

Generation

MethodPathPermissionNotes
POST/canvases/{canvasId}/generate🪄 GenerateStart an image generation. Add ?dry_run=true to price it.
POST/canvases/{canvasId}/generate-video🪄 GenerateStart a video generation. provider + duration required.
POST/canvases/{canvasId}/objects/{objectId}/regenerate🪄 GenerateRe-run an image’s saved recipe. Overrides: prompt, resolution, aspectRatio, count.
POST/canvases/{canvasId}/objects/{objectId}/remove-background🪄 GenerateRemove an image’s background (2 units).
POST/canvases/{canvasId}/combine-videos🪄 GenerateStitch video objects into one clip.

Key image fields: prompt or promptObjectId, provider/model, aspectRatio, resolution (sd/hd), count (1–10), inputObjectIds (max 10), smartRefIds (max 5), variableValues, variableObjectIds, position, mode, idempotencyKey.

Sending the same idempotencyKey twice returns the original job with idempotentReplay: true and does not charge again. --m / --ar / --q tags in the prompt override the matching body field. The response reports which value won in appliedPromptTags.

curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/generate" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "prompt": "A red apple", "aspectRatio": "1:1", "resolution": "hd" }'

Returns { jobId, placeholderIds, estimatedCost, status }. Full details, providers, and modes are on Generating images & video.

Pricing

MethodPathPermission
GET/pricing👁️ Read

The live price catalogue. It is derived server-side from the same module that prices the real charge and cannot drift from what you are billed. Cached for 60 seconds. Use it to plan a batch. Use ?dry_run=true on a generate call to price one specific job.

curl "https://derived.pro/api/cli/pricing" \
-H "Authorization: Bearer paste-your-key-here"

Jobs

MethodPathPermissionNotes
GET/canvases/{canvasId}/jobs👁️ ReadList jobs. Defaults to in-flight. ?status=all, ?limit=.
GET/canvases/{canvasId}/jobs/{jobId}👁️ ReadPoll one generation job.
GET/canvases/{canvasId}/removal-jobs/{removalJobId}👁️ ReadPoll a background-removal job.
curl "https://derived.pro/api/cli/canvases/<canvasId>/jobs/<jobId>" \
-H "Authorization: Bearer paste-your-key-here"

Job status is one of pending, processing, completed, failed, cancelled. A finished job also reports provider, mode, unitCost, generationTimeMs, resultUrls, resultObjectIds and inputImageIds. Empty arrays are omitted, not sent as []. A failed job adds errorCategory beside errorMessage.

Smart refs

MethodPathPermissionNotes
GET/canvases/{canvasId}/smart-refs👁️ ReadList smart refs on a canvas.
POST/canvases/{canvasId}/smart-refs✏️ WriteCreate a smart ref. Body: { name, description?, canvasObjectIds? }.
PATCH/canvases/{canvasId}/smart-refs/{smartRefId}✏️ WriteRename / update a smart ref.
DELETE/canvases/{canvasId}/smart-refs/{smartRefId}✏️ WriteDelete a smart ref.
POST/canvases/{canvasId}/smart-refs/{smartRefId}/images✏️ WriteAdd images. Body: { canvasObjectIds: [...] }.
DELETE/canvases/{canvasId}/smart-refs/{smartRefId}/images✏️ WriteRemove images from the smart ref.

Smart refs are built from images already on the canvas. Pass their IDs to a generation as smartRefIds, or write {Name} in the prompt, to keep a character or style consistent. See Smart refs.

Listing is project-scoped; editing is canvas-scoped. GET returns every ref you can cite from this canvas, including refs stored elsewhere in the project. Each row carries a manageable flag. When it is false, the normal case for a project-level ref, the PATCH, DELETE and image routes refuse it. Those routes are addressed through the canvas the ref belongs to.

Library

The library is your workspace’s asset registry: every generated and uploaded image.

MethodPathPermissionNotes
GET/library👁️ ReadSearch/browse. Filters: q, type, canvasId, projectId, favorites, limit (max 100), cursor.
GET/library/{imageId}👁️ ReadFull details: metadata, lineage, usage.
GET/library/{imageId}/lineage👁️ ReadGeneration ancestors of an image.
POST/library/{imageId}/star✏️ WriteStar/unstar. Body: { starred? } (omit to toggle).
curl "https://derived.pro/api/cli/library?q=apple&type=generated&limit=20" \
-H "Authorization: Bearer paste-your-key-here"

Results are paginated with a cursor. Pass the nextCursor from one response to get the next page (up to 100 per page).

Two notes on searching:

  • favorites is three-state. true returns only starred images, false returns only unstarred ones, and omitting it returns both. Any other value is a 400. A typo is never read as “no filter”.
  • A q search is keyword and meaning. It matches names, prompts and tags. The first page also runs a semantic pass, so a search for “sunset” can return an image described as “golden hour”. Every result carries matchType (keyword or semantic). The response’s semantic.applied says whether the semantic pass ran. Semantic coverage is partial, roughly four in five assets, so a semantic miss does not prove absence.

API keys

These endpoints use your browser account login, not an API key, and back the Account → API Keys screen. An API key cannot create or revoke keys. See Create an API key.

MethodPathNotes
GET/keysList your keys. Prefix only; the full key is never shown again.
POST/keysCreate a key. Body: { name, scopes }. Returns the raw key once.
DELETE/keys/{keyId}Revoke a key immediately.

Keys look like cp_live_… and carry any combination of the scopes canvas:read, canvas:write, and generate.

Errors

Every error returns the same shape:

{ "error": { "code": "VALIDATION_ERROR", "message": "A human-readable explanation." } }
StatusCodeMeaning
400VALIDATION_ERRORA field is missing or invalid. The message says which.
401UNAUTHORIZEDMissing, invalid, or revoked key.
403FORBIDDENThe key lacks the permission this endpoint needs.
402PAYMENT_REQUIREDNot enough units for this generation.
404NOT_FOUNDDoes not exist, or your key cannot see it. The response does not say which.
409CONFLICTVersion mismatch on an edit, or already-revoked key.
429RATE_LIMITEDToo many requests. Honour the Retry-After header.
500INTERNAL_ERRORServer-side error. Retry shortly.

When a generation fails, the units spent are refunded automatically.

Rate limits

Limits are per workspace, in three buckets, on a rolling one-minute window:

BucketApplies toLimit
ReadListing, reading state, polling jobs (and dry-run generations)300 / min
WriteCreating, moving, and editing objects and canvases120 / min
GenerateStarting a generation20 / min

Over the limit, requests return a 429 with a Retry-After header (in seconds). Wait that long, then continue.

One request can cost more than one. A view=thin canvas read that computes the whole-canvas structure block spends 11 from the Read bucket instead of 1. This happens only when the block cannot be derived from the returned page: an unfiltered first read of a board larger than one page. Orient once, then page with cursor. Those later reads cost 1.

Dry-run generations count against the cheaper Read bucket, not Generate.