AI Consumption Guide
How AI agents should discover and call the Yapper API.
Yapper's public API is team-scoped. API keys are created in Account → API and share the team's workspace credits.
Prefer the OpenAPI document at
/api/v1/openapi.json for exact
schemas. llms.txt and llms-full.txt are served for AI discovery:
Agent rules
- Always authenticate with
Authorization: Bearer $YAPPER_API_KEY. - Call
GET /api/v1/creditsbefore expensive work when the user asks whether a generation can run. - Poll
GET /api/v1/processes/{processId}; do not assume synchronous completion. An unfinished process reportssuggestedPollAfterSeconds: wait that long before the next read instead of a fixed interval. - Treat status values as
queued,processing,completed, orfailed. - Do not rely on Firebase paths, provider job ids, private errors, or internal
processContextfields. - Use asset ids and public asset records rather than scraping internal storage URLs.
- For
POST /api/v1/processes, sendIdempotency-Keywhen retrying or when the caller has an external job id. - To keep a character, location or prop consistent, use the workspace's
elements (
GET /api/v1/elements): pass them ininput.elements(ids or @IDs,@hero:coat-onfor one named image) and tag each in the prompt the same way. A tag in the prompt alone attaches nothing. - Hand the user the links the API returns (
webUrlon assets, processes, sessions and elements, orGET /api/v1/linksfor pages like the element library) instead of building URLs.
Music generation
Songs, beds and instrumentals at a set length, with lyrics sung as written.
Add canvas cards POST
Adds 1-50 cards in one request, already wired. Give a card a ref and later cards in the same request can wire from it with inputs: [{ sourceRef }]; sourceNodeId wires from a card already on the canvas. A wire without port goes to the first free port that takes the source's type (text into prompt, images into references); wires are checked like a drag in the app: matching types, room in the port for the card's model, and no loops. Cards without a position are laid out left to right after the existing cards. Media cards take an assetId of their type and add that asset to the session. Generation cards default to the web app's default model and settings; modelId comes from GET /models for image-gen and video-gen and from textModels in GET /canvas for text-gen, and settings are checked against that model (video settings snap to the model's nearest supported values, as in the app). A field that does not apply to the card's kind is rejected. Shows up live on the canvas in the Yapper web app. Free. Uses the processes:write scope.