Authorization

bearerAuth

AuthorizationBearer <token>

A personal API key (psk_…) or an OAuth access token (plan_at_…). Scopes: read, write.

In: header

Path Parameters

projectSlug*string

Project slug, e.g. recipe-box.

planShortId*string

Plan handle within the project, e.g. PLAN-12.

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

file?file

A PNG, JPEG, GIF or WebP image, up to 4 MB in THIS request body; past that, mint an upload URL and send storage_ref instead (images go to 10 MB).

Formatbinary

storage_ref?string

The reference returned by POST …/images/upload-url, after the bytes have been PUT to its signed URL. Send filename and content_type with it.

filename?string

With storage_ref: the file name, used for the alt text and, when content_type is absent, the image type. Defaults to image.

content_type?string

With storage_ref: the image type you declared when minting the upload URL. The bytes are checked either way.

url?string

A public https image URL, fetched by the server (no redirects, 8 MB max, private addresses refused).

attachmentId?string

An image already on this plan: the retry after a 409, so the image is not uploaded twice.

Formatuuid

alt?string

Alt text. Defaults to the file name.

spec?string

A SPEC-n handle: append the image to the end of this spec.

epic?boolean

Append the image to the end of the plan’s epic.

expectedRevision?string

With spec or epic: the revision from your last read of that spec or epic. The append always compares against the revision it read; this lets you pin yours. An updatedAt timestamp from an older client is still accepted.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/plans/string/images"

{  "attachmentId": "96b9bbac-86d3-4497-9e0c-1f8e3803eddb",  "url": "string",  "markdown": "string",  "appendedTo": "string",  "revision": "string"}

View as Markdown Open in Claude Open in ChatGPT

Add an image to a plan, optionally appended to a spec or the epic

Authorization

Path Parameters

Request Body

Response Body

201application/json

401application/json

404application/json

409application/json

413application/json

422application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`