API reference

The Spoken scan, from an API call: photos in, a saved build out — owned by your Spoken account, public on spoken.fyi, every part identified, priced and linked. Build pages open for anyone with the link while the rest of Spoken is in its private beta; the API answer is complete regardless. Pass job for a poster and/or a film in the same call; stream: true for progress events and the parts as one final event (no build is saved).

The same scan as a JOB: a job id in about a second, and the work keeps going after you hang up. Poll GET /api/v1/scans/{id} (free) for progress and the result. save: false runs it headless — parts under the job id, nothing saved to spoken.fyi (bom only).

A parts list in (pasted text, or a CSV / XLSX / PDF file as base64), rows out. Free. Send the rows as parts on POST /api/v1/scans and the list becomes the build: every row a part, the photo places what it can.

An upload slot for one photo: PUT the bytes to its upload_url with its headers (no key needed, up to 12 MB, about an hour), then scan with image_url set to its photo_url. For photos you hold as files — a phone photo is bigger than a request can carry as base64. A client token may ask for one, so a phone can send its photo straight up. Free.

Your server mints a short-lived client token (ct_…) with its secret key; your browser or app presents it to start ONE scan job (and read it) directly — no proxy, and a copied token is worth one scan, not your balance. Free.

A scan job: status, progress (0-100), and the full result once done. Free — poll every 2 s; a retry after an Idempotency-Key returns the same job.

A build record: parts, prices, buy links, pin geometry and media — the same read the build page makes.

Delete one of your builds: the photos, poster plates and films we host, then the record. Free.

Delete everything held for one of your users, by the pseudonymous user_ref you sent with their scans: builds, media, scan jobs. Billing rows stay, unlinked. Free.

Search the component catalog (parts + brands).

Usage, credit balance and plan status, by day or by month — with the plan's 50 / 80 / 100% warnings. Free.

Another poster from a build you already have — any of the product's poster styles; variant 1-99 is the app's Remake on the 9:16 styles.

The app's Remake button: a new film from a build you already have (2 remakes per build per day, as in the app). Poll the same path with GET (free).