Skip to Content
Agents & APICanvases & objects

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 visibility of private, selected_users, or org_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:

TypeWhat it is
imageA picture, uploaded by you or produced by a generation.
textA plain text label or annotation.
promptAn amber template block. Its text can contain <variable> placeholders and {SmartRefName} references.
variableA block whose content must read <name> : value. It fills in the matching <variable> placeholder during generation.
videoA 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:

ParameterValuesWhat it does
viewthin or fullfull (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.
limit1–500Page size. 500 is the default and the ceiling. A bigger number is clamped, not rejected.
cursoropaque stringPass back the nextCursor from the previous response to get the next page.
typeimage, text, prompt, variable, video, shape, sticker, empty_imageFilters 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.

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 200 does not mean every id landed. Ids that no longer exist or are not the right type do not fail the call. The response has a results entry per id (applied, failed, or skipped) plus a summary. Check summary.failed and 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.