Agent API

The Agent API is the supported way for an approved integration to create and inspect YADL explanatory diagrams without browser automation or direct database access. It lives under /api/v1/agent and enforces the API-key scopes described in API keys and scopes.

What it supports

The current verified workflow supports five explanatory composition families: architecture, comparison, process flow, step-by-step, and timeline. A brief selects square, portrait, or landscape output and a duration from 5 to 15 seconds. Composition returns editable YADL source; it does not publish or overwrite a document by itself.

Use the capability endpoint before building a workflow:

GET /api/v1/agent/capabilities
Authorization: Bearer yadl_your_secret_key

It reports the release profile, supported families, aspect ratios, duration limits, and known limitations. GET /api/v1/agent/release reports the qualified release matrix when the release surface is enabled.

Recommended workflow

1. Discover capabilities and, if useful, search authorized templates, components, icons, backgrounds, brands, or verified recipes with GET /api/v1/agent/resources (catalog:read).
2. Send a structured brief to POST /api/v1/agent/compose (catalog:read), or use POST /api/v1/agent/repair for a bounded repair of at most three attempts.
3. Validate and inspect the returned workspace with POST /api/v1/agent/validate and POST /api/v1/agent/inspect (preview:read). Treat returned issues as actionable source feedback.
4. Optionally queue up to eight private PNG checkpoints with POST /api/v1/agent/storyboards (preview:read), then poll the returned status path. Frame paths remain authenticated; do not turn them into public links.
5. Create or update the document with PUT /api/v1/agent/documents (documents:write). New documents return an ID and version. Updates must include that ID and the version you last read.
6. Read GET /api/v1/agent/exports/quota before requesting video. Submit POST /api/v1/agent/exports with a saved document ID and a stable idempotency key (exports:write), then poll GET /api/v1/agent/exports/:id (exports:read).

Save conflicts and retries

Document saves use optimistic concurrency. When another save has produced a newer version, YADL returns 409 DOCUMENT_VERSION_CONFLICT with the expected and actual version values. Preserve your local draft, read the newest version, then decide whether to merge it or save a separate copy.

Exports require an idempotency key that is 8–200 characters. Reuse the same key only when retrying the same export request; YADL returns the existing export rather than reserving quota or queueing a duplicate. The service automatically selects a plan-compatible output size while keeping the document's authored frame.

Limits and diagnostics

The verified agent profile accepts self-contained source or a local multi-file workspace. It does not currently certify catalog dependencies, imported assets, chart generation, narration, social publishing, direct-canvas editing, or unrestricted visual types. Storyboards and exports are asynchronous; an accepted request is not a completed artifact.

Validation, composition, quota, and export errors are structured. Common responses include 422 for invalid source or preflight issues, 409 for a save conflict or retention limit, 429 for quota exhaustion, and 403 for a scope or plan-policy restriction. Do not retry a permanent validation or authorization error unchanged.

Package a completed delivery

After a storyboard and its matching export are both completed, GET /api/v1/agent/packages (exports:read) can return the editable source, pinned dependency metadata, poster metadata, authenticated video retrieval paths, and validation summary. YADL rejects a package when the storyboard and export were not made from the same immutable source.

For the complete route schemas and current response bodies, use the generated API reference. For a user-authorized tool connection instead of direct HTTP integration, see MCP.