REST API

YADL's REST API is the integration boundary for account-aware documents, catalog data, exports, and notifications. The interactive API reference is generated from the currently registered Fastify routes and is the authoritative list of paths, inputs, responses, and error shapes.

Base URL and authentication

Use the deployment's /api/v1 base path. Requests that act on an account require an Authorization: Bearer … header. Browser sessions, approved OAuth access tokens, and owner-bound YADL API keys authenticate as the owner; a key never grants access to another user's documents, exports, or private files.

Authorization: Bearer yadl_your_secret_key
Accept: application/json

Do not put a secret in browser code, a public repository, screenshots, prompts, or URLs. Create and manage a key from Settings → Security → Generate API Key; see API keys and scopes.

Start with the live contract

Open API reference in the same YADL environment that your integration will use. It provides the current OpenAPI document in JSON and YAML as well as the interactive reference. Use it instead of copying an endpoint list into an integration, because available public catalog, account, and export operations can evolve.

For all write operations, handle structured errors rather than assuming a request succeeds. Typical responses identify validation, authentication, authorization, quota, ownership, or optimistic-concurrency problems without returning private source or credentials.

Integration boundaries

• Public catalog and published-content reads can be available without an account; owner work, private files, exports, settings, and API-key management are authenticated.
• The REST API does not provide database access, administrator operations, worker credentials, or unrestricted storage URLs.
• Video rendering remains asynchronous. Submit an export, then inspect its status before using its owner-scoped preview or download path.
• For AI-assisted composition, validation, storyboards, and idempotent exports, use the dedicated Agent API rather than trying to automate the editor.

Safe integration practice

Keep secrets in your server or connector configuration, use separate keys for separate environments, and disable or delete a key immediately if it may have been exposed. Design retries carefully: only use a stable idempotency key for a request you intend to replay. The agent export endpoint documents this workflow in Agent API.