This page covers the data model your API key works with, and how to create, read, update, and delete the things on a canvas. To start a generation, skip to Generating images & video.
How everything fits together
derived organises your work in three layers:
- Projects — workspace containers. A project holds canvases and controls who in
your workspace can see them. All projects are the same kind. They differ only by a
visibilityofprivate,selected_users, ororg_shared. There is no special “personal” project type. - Canvases — infinite 2D boards. Each canvas belongs to one project and holds a set of objects.
- Objects — everything on a canvas: images, text, prompt blocks, variable blocks, and videos.
Your API key is bound to a single workspace (organisation). It can reach every project and canvas in that workspace, subject to the project’s visibility rules.
Creating a project automatically creates one Untitled Canvas inside it.
Object types
The API works with five object types:
| Type | What it is |
|---|---|
image | A picture, uploaded by you or produced by a generation. |
text | A plain text label or annotation. |
prompt | An amber template block. Its text can contain <variable> placeholders and {SmartRefName} references. |
variable | A block whose content must read <name> : value. It fills in the matching <variable> placeholder during generation. |
video | A generated video clip. |
Generation creates only images and videos. You add text, prompt, and variable blocks directly. Prompt and variable blocks are used for templated generation; see Generating images & video. For how these blocks look and work in the browser, see Adding things to a canvas.
A note on coordinates
Positions use a center origin. An object’s x / y is the center of the
object, not its top-left corner. Moving an object to { x: 0, y: 0 } centers it on
the origin. It does not put its corner there.
Reading a canvas
The main read is canvas state. It returns everything on the canvas as structured JSON that code and AI can reason about without looking at the picture:
curl "https://derived.pro/api/cli/canvases/<canvasId>/state" \
-H "Authorization: Bearer paste-your-key-here"
The response holds the canvas metadata, the current viewport (zoom and pan), every object with its position and type-specific fields, and a summary of the board:
{
"canvas": { "id": "...", "name": "Summer Launch", "project": { "id": "...", "name": "..." } },
"viewport": { "zoom": 0.8, "panX": 120, "panY": -40 },
"objects": [
{
"id": "...",
"type": "image",
"position": { "x": 100, "y": 100, "width": 512, "height": 512, "rotation": 0 },
"src": "https://...",
"generationPrompt": "A red apple",
"status": "complete"
}
],
"summary": { "totalObjects": 12, "generatedImages": 8, "uploadedImages": 2, "inProgress": 1 }
}Images that are still generating show a status of generating. Finished ones show
complete. Transient placeholders that are not real objects yet are filtered out.
Reading a big canvas
A board can hold thousands of objects. This endpoint is paginated. It takes four query parameters:
| Parameter | Values | What it does |
|---|---|---|
view | thin or full | full (the default) returns every field. thin drops six per-image fields and replaces each generationPrompt with a key into a shared prompts dictionary at the top of the response. Much smaller on a board where one prompt produced fifty images. |
limit | 1–500 | Page size. 500 is the default and the ceiling. A bigger number is clamped, not rejected. |
cursor | opaque string | Pass back the nextCursor from the previous response to get the next page. |
type | image, text, prompt, variable, video, shape, sticker, empty_image | Filters server-side. An unrecognised value is a 400, never an empty page. |
Every response carries a nextCursor (null on the last page) and a summary with
totalObjectsOnCanvas. That is the true row count, always a real number, whether or
not this page shows all of it.
A cursor does not remember your filter. On a filtered read, send type again
on every page. Otherwise the walk silently continues unfiltered from that point.
Under a type filter, summary describes that type only, and a summary.filter
field appears to say so.
The structure block
Ask for view=thin without a cursor and the response also carries a structure
block. It summarises the whole canvas, not only the current page. A script or an
assistant can use it to understand a board too large to read in full: when the work
happened, which images came from which, which prompts produced what, what is starred,
and how far the board extends.
The block does not approximate. Every object is either named by id or counted in a
stated total, and the two must add up. If they do not, the block says so. On a canvas
over 5,000 objects it returns available: false with a reason instead of a partial
answer.
Computing it costs 10 extra requests from your read budget on top of the 1 the
request itself costs. The extra cost applies only when it cannot be derived from the
page already returned. Read it once, then page through with cursor. Those later
pages cost 1.
Fetching specific objects
Fetch specific objects by id instead of re-reading the board. This returns the same
full detail as view=full, for up to 25 ids:
curl "https://derived.pro/api/cli/canvases/<canvasId>/objects?ids=<id1>,<id2>" \
-H "Authorization: Bearer paste-your-key-here"
Ids that are not on this canvas are returned in a notFound array. The request does
not fail.
Creating objects
Each object type has its own create endpoint. They all return the new object with its
assigned id and position.
Image
Upload an image from a URL or as base64. The image is stored, registered in your library, and placed on the canvas in one call:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/objects/image" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "imageUrl": "https://example.com/photo.png", "left": 100, "top": 100 }'Use imageUrl or imageBase64 (with a mimeType), not both. Uploads are
limited to 10 MB. URL fetches are checked for safety. Private and internal
addresses are rejected.
Updating objects
Each kind of edit has its own endpoint. There is no single update call.
Move or resize
Update any of x, y, width, height. Rotation is not editable through the API.
curl -X PATCH "https://derived.pro/api/cli/canvases/<canvasId>/objects/<objectId>/position" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "x": 400, "y": 200, "width": 256 }'
Edit text, prompt, or variable content
Each of these has its own PATCH endpoint: /objects/<objectId>/text,
/objects/<objectId>/prompt, and /objects/<objectId>/variable.
curl -X PATCH "https://derived.pro/api/cli/canvases/<canvasId>/objects/<objectId>/prompt" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "content": "A <color> pear on a marble surface" }'
Rename or re-tag an image
For image objects you can update the display name and tags. Both live on the
library entry behind the image:
curl -X PATCH "https://derived.pro/api/cli/canvases/<canvasId>/objects/<objectId>/metadata" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "displayName": "Hero — red apple", "tags": ["hero", "fruit"] }'
Crop an image
Crops are non-destructive. The original is untouched. Coordinates are normalised
(0–1). cropLeft/cropTop is the top-left of the visible region:
curl -X PATCH "https://derived.pro/api/cli/canvases/<canvasId>/objects/<objectId>/crop" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "cropLeft": 0.1, "cropTop": 0.1, "cropWidth": 0.8, "cropHeight": 0.8 }'
To remove a crop, send { "clear": true }.
Tag many objects at once
The endpoint above tags one object at a time. A bulk route tags up to 100 objects in a single call:
curl -X PATCH "https://derived.pro/api/cli/canvases/<canvasId>/objects/metadata" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "objectIds": ["id-1", "id-2"], "tags": ["hero", "fruit"] }'
Two things to know before you use it:
- Tags are a full replace, not an addition. The array you send becomes each object’s entire tag set. An empty array clears them. To keep an object’s existing tags, read them first and include them.
- A
200does not mean every id landed. Ids that no longer exist or are not the right type do not fail the call. The response has aresultsentry per id (applied,failed, orskipped) plus asummary. Checksummary.failedand retry only those ids.
This route sets tags only. displayName stays on the single-object endpoint. Tags
live on the library entry, so two canvas objects backed by the same library image are
tagged together, including one on a canvas you did not name.
Content edits (text, prompt, variable, crop) accept an optional expected_version. If
you pass it and someone else changed the object in the meantime, you get a
409 CONFLICT instead of overwriting their change. Use it when more than one tool
edits the same canvas. The bulk tag route takes the plural expectedVersions, a map
of object id to version. It fails only the objects that do not match. The rest of the
batch is written.
A version check on tags guards “is this still the object I read?”. It catches a move, a crop, or a content edit. It is blind to a concurrent tag write, because tags do not live on the object row. Two tools tagging the same object both pass the check, and the later one wins.
Duplicate an object
Makes an independent copy on the same canvas, offset slightly from the original:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/objects/<objectId>/duplicate" \
-H "Authorization: Bearer paste-your-key-here"
Deleting objects
Delete objects in a batch by ID, up to 100 at a time. Unknown IDs are skipped. Retrying is safe:
curl -X DELETE "https://derived.pro/api/cli/canvases/<canvasId>/objects" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "objectIds": ["id-1", "id-2"] }'
This removes the objects from this canvas only. The library images behind them are not deleted. They are independent workspace assets that other canvases may use.
Managing canvases
Create a canvas
A canvas always belongs to a project. projectId is required:
curl -X POST "https://derived.pro/api/cli/canvases" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Summer Launch", "projectId": "<projectId>" }'To create a project, POST https://derived.pro/api/cli/projects with a name. This also creates
a starter canvas.
Rename, re-cover, or move it
curl -X PATCH "https://derived.pro/api/cli/canvases/<canvasId>" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Summer Launch v2" }'You can also set coverImageUrl or move the canvas to another project with
projectId.
Duplicate the whole canvas
Clones the canvas and all its objects:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/duplicate" \
-H "Authorization: Bearer paste-your-key-here"Delete it
curl -X DELETE "https://derived.pro/api/cli/canvases/<canvasId>" \
-H "Authorization: Bearer paste-your-key-here"Deleting a canvas removes its objects too. It does not delete the underlying library images. Those are workspace assets that outlive any one canvas.
Moving the camera (viewport)
The viewport is where the canvas is scrolled and zoomed to. Set it so a teammate or a screenshot opens at the right place:
curl -X PATCH "https://derived.pro/api/cli/canvases/<canvasId>/viewport" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "zoom": 0.8, "panX": 0, "panY": 0 }'
zoom ranges from 0.05 to 20. Updates are last-write-wins. There is no version
check.
Next: Generating images & video.