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
| Method | Path | Permission |
|---|---|---|
| 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
| Method | Path | Permission |
|---|---|---|
| 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
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /projects | 👁️ Read | List projects. Add ?include_archived=true to include archived ones. |
| POST | /projects | ✏️ Write | Create a project (and a starter canvas). Body: { name? }. |
| PATCH | /projects/{projectId} | ✏️ Write | Rename a project. Body: { name }. |
| GET | /projects/{projectId}/canvases | 👁️ Read | List 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
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /canvases | 👁️ Read | List canvases. Paginated: limit (1–100, default 20), offset. The response carries pagination.hasMore. |
| POST | /canvases | ✏️ Write | Create a canvas. Body: { name, projectId } (both required). |
| GET | /canvases/{canvasId}/state | 👁️ Read | Canvas state: objects, viewport, summary. Paginated: view (thin/full), limit (1–500), cursor, type. |
| PATCH | /canvases/{canvasId} | ✏️ Write | Update name, coverImageUrl, or projectId. |
| DELETE | /canvases/{canvasId} | ✏️ Write | Delete the canvas and its objects. |
| POST | /canvases/{canvasId}/duplicate | ✏️ Write | Clone the canvas and all objects. Body: { name? }. |
| PATCH | /canvases/{canvasId}/viewport | ✏️ Write | Set 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.
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /canvases/{canvasId}/objects?ids=… | 👁️ Read | Full detail for up to 25 object ids. Unknown ids are returned in notFound. |
| PATCH | /canvases/{canvasId}/objects/metadata | ✏️ Write | Bulk 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 | ✏️ Write | Upload from imageUrl or imageBase64 (+mimeType). Optional left, top, tags. Max 10 MB. |
| POST | /canvases/{canvasId}/objects/text | ✏️ Write | Body: { content, x?, y?, width?, height?, fontSize?, fontFamily?, color? }. |
| POST | /canvases/{canvasId}/objects/prompt | ✏️ Write | Body: { content, x?, y?, width?, height? }. Supports <var> and {SmartRef} tokens. |
| POST | /canvases/{canvasId}/objects/variable | ✏️ Write | Body: { name, value, x?, y?, width?, height? }. |
| PATCH | /canvases/{canvasId}/objects/{objectId}/position | ✏️ Write | Move/resize: any of x, y, width, height. |
| PATCH | /canvases/{canvasId}/objects/{objectId}/text | ✏️ Write | Update text content. |
| PATCH | /canvases/{canvasId}/objects/{objectId}/prompt | ✏️ Write | Update content. Optional expected_version. |
| PATCH | /canvases/{canvasId}/objects/{objectId}/variable | ✏️ Write | Update name and/or value. Optional expected_version. |
| PATCH | /canvases/{canvasId}/objects/{objectId}/metadata | ✏️ Write | Image only: update displayName and/or tags. |
| PATCH | /canvases/{canvasId}/objects/{objectId}/crop | ✏️ Write | Set a 0–1 crop, or { clear: true } to remove it. |
| POST | /canvases/{canvasId}/objects/{objectId}/duplicate | ✏️ Write | Copy an object on the same canvas (+20px offset). |
| POST | /canvases/{canvasId}/objects/{objectId}/extract-frame | ✏️ Write | Extract a still frame from a video object. |
| DELETE | /canvases/{canvasId}/objects | ✏️ Write | Batch 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
| Method | Path | Permission | Notes |
|---|---|---|---|
| POST | /canvases/{canvasId}/generate | 🪄 Generate | Start an image generation. Add ?dry_run=true to price it. |
| POST | /canvases/{canvasId}/generate-video | 🪄 Generate | Start a video generation. provider + duration required. |
| POST | /canvases/{canvasId}/objects/{objectId}/regenerate | 🪄 Generate | Re-run an image’s saved recipe. Overrides: prompt, resolution, aspectRatio, count. |
| POST | /canvases/{canvasId}/objects/{objectId}/remove-background | 🪄 Generate | Remove an image’s background (2 units). |
| POST | /canvases/{canvasId}/combine-videos | 🪄 Generate | Stitch 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
| Method | Path | Permission |
|---|---|---|
| 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
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /canvases/{canvasId}/jobs | 👁️ Read | List jobs. Defaults to in-flight. ?status=all, ?limit=. |
| GET | /canvases/{canvasId}/jobs/{jobId} | 👁️ Read | Poll one generation job. |
| GET | /canvases/{canvasId}/removal-jobs/{removalJobId} | 👁️ Read | Poll 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
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /canvases/{canvasId}/smart-refs | 👁️ Read | List smart refs on a canvas. |
| POST | /canvases/{canvasId}/smart-refs | ✏️ Write | Create a smart ref. Body: { name, description?, canvasObjectIds? }. |
| PATCH | /canvases/{canvasId}/smart-refs/{smartRefId} | ✏️ Write | Rename / update a smart ref. |
| DELETE | /canvases/{canvasId}/smart-refs/{smartRefId} | ✏️ Write | Delete a smart ref. |
| POST | /canvases/{canvasId}/smart-refs/{smartRefId}/images | ✏️ Write | Add images. Body: { canvasObjectIds: [...] }. |
| DELETE | /canvases/{canvasId}/smart-refs/{smartRefId}/images | ✏️ Write | Remove 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.
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /library | 👁️ Read | Search/browse. Filters: q, type, canvasId, projectId, favorites, limit (max 100), cursor. |
| GET | /library/{imageId} | 👁️ Read | Full details: metadata, lineage, usage. |
| GET | /library/{imageId}/lineage | 👁️ Read | Generation ancestors of an image. |
| POST | /library/{imageId}/star | ✏️ Write | Star/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:
favoritesis three-state.truereturns only starred images,falsereturns only unstarred ones, and omitting it returns both. Any other value is a400. A typo is never read as “no filter”.- A
qsearch 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 carriesmatchType(keywordorsemantic). The response’ssemantic.appliedsays 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.
| Method | Path | Notes |
|---|---|---|
| GET | /keys | List your keys. Prefix only; the full key is never shown again. |
| POST | /keys | Create 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." } }| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR | A field is missing or invalid. The message says which. |
| 401 | UNAUTHORIZED | Missing, invalid, or revoked key. |
| 403 | FORBIDDEN | The key lacks the permission this endpoint needs. |
| 402 | PAYMENT_REQUIRED | Not enough units for this generation. |
| 404 | NOT_FOUND | Does not exist, or your key cannot see it. The response does not say which. |
| 409 | CONFLICT | Version mismatch on an edit, or already-revoked key. |
| 429 | RATE_LIMITED | Too many requests. Honour the Retry-After header. |
| 500 | INTERNAL_ERROR | Server-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:
| Bucket | Applies to | Limit |
|---|---|---|
| Read | Listing, reading state, polling jobs (and dry-run generations) | 300 / min |
| Write | Creating, moving, and editing objects and canvases | 120 / min |
| Generate | Starting a generation | 20 / 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.