Yapper Docs

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/credits before 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 reports suggestedPollAfterSeconds: wait that long before the next read instead of a fixed interval.
  • Treat status values as queued, processing, completed, or failed.
  • Do not rely on Firebase paths, provider job ids, private errors, or internal processContext fields.
  • Use asset ids and public asset records rather than scraping internal storage URLs.
  • For POST /api/v1/processes, send Idempotency-Key when 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 in input.elements (ids or @IDs, @hero:coat-on for 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 (webUrl on assets, processes, sessions and elements, or GET /api/v1/links for pages like the element library) instead of building URLs.

On this page