Reference

REST API

Every endpoint, every field. Projects are the resource.


Base URL	`https://api.trypitch.co`
Auth	`Authorization: Bearer pk_...`
Content type	`application/json`
Create and prompt response	`202 Accepted` with a project object

#The project object

Every endpoint that touches a project returns this shape.

Field	Type	Notes
`id`	string	Use it to poll and to prompt
`title`	string	Derived from the prompt, URL, topic, or file name
`status`	string	`working`, `ready`, `failed`, `empty`
`busy`	boolean	True while `status` is `working`
`prompt`	string	The first message
`options`	object	Creation preferences
`outputs`	array	Newest first. `kind` (`video`, `pdf`, `html`, `thumbnail`), `url`, `res?`, `label?`, `createdAt`
`thumbnailUrl`	string \| null	Poster frame for videos
`shareUrl`	string \| null	Only if sharing was turned on in the app
`error`	string \| null	Set when `status` is `failed`
`scenes`	array?	Video flows. `id`, `index`, `start`, `end`, `dur`, `label?`, `type?`
`slides`	array?	Decks. `index`, `title?`
`createdAt`	string	ISO 8601
`updatedAt`	string	ISO 8601

scenes and slides are read from the live workspace and come back only on GET /v1/projects/:id, creation, and prompt responses, not on the list.

#POST /v1/projects

Create a project and send its first prompt. Work is usage-metered as it runs.

Field	Type	Required	Notes
`flow (deprecated)`	string	no	Deprecated compatibility hint. Accepted but ignored.
`prompt`	string	unless uploads	What to make: the product URL and brief, the topic, the instructions
`options`	object	no	Flow options, below
`uploads`	array	no	`{ fileBase64, fileName }` entries. See Files
`name`	string	no	Workspace slug, unique per user. Made from the title if omitted. No `/` or `\`, cannot start with a dot

Common outcome options

Outcome	Billing	Options
`launch-video`	Metered	`resolution` (`720p`, `1080p` default, `4k`; sets the price; every export is 60 fps), `narration` (default true; false saves 40 credits), `music` (track filename from the shared library)
`demo-video`	Metered	`url` (also read from the prompt), `instructions`, `script` (your own narration), `voice`, `background`, `shape`, `inset`, `browserHeader`, `fps` (`30` or `60`; default the recording's own)
`deck`	Metered	`topic`, `slideCount`, `headings`, `template`, `mode` (`recreate` rebuilds an uploaded deck, `preserve` keeps its layout; setting it makes the project an enhance)
`recording-edit`	Metered	`productName` (intro card), `productUrl` (outro card), `instructions`, `fps` (`30` or `60`; default the recording's own)

bash

curl -X POST https://api.trypitch.co/v1/projects \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "https://acme.com — 60 second launch film for an AI notetaker. Confident, fast.",
    "options": { "resolution": "1080p", "narration": true }
  }'

bash

curl -X POST https://api.trypitch.co/v1/projects \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Seed round deck for an AI video startup",
    "options": { "slideCount": 10 }
  }'

Returns 202 with the project. Fails with 402 if the balance is too low and413 or 415 for a bad upload.

#GET /v1/projects

List your projects, newest first. Free.

Query	Notes
`limit`	Default 50, max 100

json

{ "data": [ { "id": "cm4x...", "status": "ready", "outputs": [ ... ], ... } ], "total": 37 }

#GET /v1/projects/:id

One project, with scenes or slides. Returns 404 if it does not exist or is not yours. Free. This is what you poll.

#POST /v1/projects/:id/prompt

Send the agent a usage-metered follow-up. It works asynchronously; poll the project.

Field	Type	Required	Notes
`text`	string	yes	What to change
`scene`	string	no	A scene id from `scenes`, to scope the request
`slide`	number	no	A 1-based slide index, for decks
`delivery`	`"queue" \| "steer"`	no	Queue behind active work (default), or steer the active run

bash

curl -X POST https://api.trypitch.co/v1/projects/cm4x8k2p90001abcd/prompt \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Make slide 4 a two-column comparison.", "slide": 4 }'

Returns 202 with the project. If the agent is already working, the prompt queues behind it unless delivery: "steer" is provided.

#POST /v1/projects/:id/export

Start an export with optional res (720p, 1080p, or 4k). Returns 202 with export status. Poll GET on the same path until running is false.

#GET /v1/credits

Balance, plan, and the 20 most recent ledger entries. Free. See Credits.

#GET /v1/pricing

Usage-metering rates and indicative launch export tiers. No key needed. The payload is in Credits.

#Not there yet

There are no webhooks, so you have to poll. There are no idempotency keys, so a retried create can make a second project. There is no cursor pagination on the project list, only a limit. Stop, delete, and share are not exposed through the public API; exports are.