Yapper API
Api reference
POST
/sessions/{sessionId}/canvas/runs

Runs generation cards (image-gen, video-gen, text-gen) in wiring order and charges team credits as each card starts. A card starts once the cards feeding it have finished and reads their selected output; a card fed by one that is still generating waits for it. scope selection (default) runs exactly nodeIds; downstream also runs every card they feed. Omit nodeIds to run every generation card. Each card gets a new version that holds this run's settings, so editing a card while it waits does not change what it makes. The run continues on the server with no client connected; poll GET /canvas/runs/{runId}. dryRun: true quotes the run (creditsEstimated per card and canStart) without starting or charging anything. The balance must cover the estimate up front (insufficient_credits otherwise); LLM cards on an included model draw from Included Agent Usage first. Always send an Idempotency-Key on real runs. Uses the processes:write scope.

Authorization

bearerAuth processes:write
AuthorizationBearer <token>

In: header

Scope: processes:write

Path Parameters

sessionId*string

Header Parameters

Idempotency-Key?string

Optional key that makes the request safe to retry: a retry with the same key returns the run the first request started instead of charging again. Scoped to the credential and session.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/sessions/string/canvas/runs" \  -H "Content-Type: application/json" \  -d '{}'
{  "dryRun": true,  "creditsEstimated": 0,  "canStart": true,  "reason": "string",  "nodes": [    {      "nodeId": "string",      "step": 0,      "kind": "string",      "label": "string",      "creditsEstimated": 0    }  ]}
{  "id": "string",  "status": "running",  "scope": "selection",  "startNodeIds": [    "string"  ],  "creditsEstimated": 0,  "createdAt": "2019-08-24T14:15:22Z",  "finishedAt": "2019-08-24T14:15:22Z",  "endedReason": "string",  "suggestedPollAfterSeconds": 0,  "nodes": [    {      "nodeId": "string",      "step": 0,      "kind": "string",      "label": "string",      "state": "pending",      "reason": "needsPrompt",      "detail": "string",      "processIds": [        "string"      ],      "outputs": [        {          "assetId": "string",          "type": "image",          "url": "string",          "thumbnailUrl": "string",          "width": 0,          "height": 0,          "duration": 0,          "name": "string"        }      ],      "texts": [        "string"      ],      "errors": [        "string"      ]    }  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Remove a workspace item by path DELETE

Removes an item from the tree; a folder goes with everything in it. Never deletes assets, and does not always take media out of the session: media that was only filed here from elsewhere leaves it (unlinkedAssetIds), while media created in the session, or that joined it another way such as being used in a generation, stays in it unfiled (unfiledAssetIds). To take media out of the session itself, use DELETE /sessions/{sessionId}/assets. Removing the brief clears it. The workspace root cannot be removed. Addresses the item by its path; /workspace/nodes/{nodeId} does the same by id. The change shows up in the Yapper web app and is recorded with the API key or MCP client that made it; the in-app Yapper agent in that session is told about it on its next turn. Free. Uses the processes:write scope.

Move an asset to the trash DELETE

Moves an asset to the trash, as deleting it in the web app does: it leaves the library and every session, and GET /assets/{assetId} returns not_found. It is permanently deleted 30 days later (purgeAfter); until then PATCH with trashed: false restores it. A session whose chosen image was this asset goes back to following its newest generation. Trashing an already-trashed asset is a no-op. To take an asset out of one session only, use DELETE /sessions/{sessionId}/assets. Free.