Skip to Content
Agents & APIUse the API directly

Your own script or integration can call the derived API directly, without an AI assistant. It is a plain HTTP/JSON API. Any language that can make an HTTP request can use it.

To let an assistant drive instead, see Connect an AI assistant. It uses the same key and the same permissions, and discovers the API for you.

What you’ll need

  • An API key — see Create an API key. It is sent as a bearer token on every request.
  • The base URL for the API:
https://derived.pro/api/cli

Every path below is relative to that base. For example, listing canvases is a GET to https://derived.pro/api/cli/canvases.

Authentication

Send your key in the Authorization header as a bearer token on every request:

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

Three things to know:

  • Keys are scoped. Each key carries some combination of Read, Write, and Generate permission. A request without the matching permission returns a permission error. See Create an API key.
  • One workspace per key. A key reaches every canvas in the workspace it was created under. It cannot see other workspaces.
  • Keep it secret. Treat the key like a password. If it leaks, revoke it on the API Keys page and create a new one.

Never put your key in client-side code or a public repo. Anyone with the key can act in your workspace until you revoke it.

The core loop

Almost every task follows the same shape:

Find a canvas

List your canvases, or create one. Read its state to see the objects on it.

Add or arrange objects

Upload images, add text, add prompt and variable blocks, or move objects.

Generate

Start an image or video generation. It runs in the background and spends units (unless you've connected your own Fal.ai key).

Poll the job

A generation returns a job, not the image. Check the job status until it is completed. The result lands on the canvas.

Two pages cover each half in detail:

Quickstart

The whole loop end to end. Replace paste-your-key-here and the placeholder IDs with real values.

List your canvases

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

The response is a list of canvases, each with an id. Pick one as <canvasId>.

Check the cost of a generation

Add ?dry_run=true to a generate request. derived returns the estimated cost and your balance without spending anything:

curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/generate?dry_run=true" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "prompt": "A serene mountain landscape at sunset", "aspectRatio": "16:9" }'

The response looks like:

{ "dryRun": true, "estimatedCost": 16, "balance": 200, "wouldSucceed": true, "reason": null }

Start the generation

Without the dry_run flag the same request runs. The response is a job:

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 serene mountain landscape at sunset", "aspectRatio": "16:9" }'
{ "jobId": "7c1e...", "placeholderIds": ["a91f..."], "estimatedCost": 16, "status": "pending" }

Poll until it’s ready

Use the jobId to check the job. Repeat every few seconds until status is completed:

curl "https://derived.pro/api/cli/canvases/<canvasId>/jobs/<jobId>" \
-H "Authorization: Bearer paste-your-key-here"

When done, the result image is on the canvas. Its URL is in resultUrls. Read the canvas state again to see it in place.

Errors and limits at a glance

Every error returns the same JSON shape and a matching HTTP status code:

{ "error": { "code": "VALIDATION_ERROR", "message": "aspectRatio must be one of …" } }
StatusCodeWhat it usually means
400VALIDATION_ERRORA field in the request body is missing or invalid.
401UNAUTHORIZEDMissing, invalid, or revoked key.
403FORBIDDENThe key lacks the permission this endpoint needs.
402PAYMENT_REQUIREDNot enough units for this generation.
404NOT_FOUNDThe canvas, object, or job does not exist, or your key cannot see it.
409CONFLICTThe resource changed since you read it (e.g. an edit version mismatch).
429RATE_LIMITEDToo many requests. Wait for the seconds in the Retry-After header, then retry.

Requests are rate-limited per workspace, in three buckets: reads, writes, and generations. On a 429, wait the number of seconds in the Retry-After header and try again.

The full list of endpoints, with a curl example for each, is in the API reference.