REST API

Base URL: https://api.falcata.io/api/v1

One versioned surface covers the whole platform — content, tasks, workflows, media, analytics, notifications, search, access — described end to end by a generated OpenAPI 3.1 specification(opens in a new tab) and browsable in the full reference. GET /api/v1 itself returns an index of every discovery document.

Authentication

Every request carries Authorization: Bearer <token> — see Authentication. Anonymous requests get a 401 whose WWW-Authenticate header links the OAuth discovery documents.

Conventions

• Versioning is path-based (/api/v1/); breaking changes mean a new version prefix.
• Envelope: success responses are { "data": ..., "meta": ... }; errors are { "error": { "code": ..., "message": ... } } with a non-2xx status.
• Errors use standard status codes — 400 validation, 401 credential, 403 permission, 404 not found, 429 rate limit, 500 server. Branch on the error code, not the message text.
• Rate limits: 600 requests/minute per token, burst 100, announced in RateLimit / RateLimit-Policy headers; 429 carries Retry-After.
• Idempotency: pass Idempotency-Key on writes; a retry within 24 hours replays the original outcome instead of repeating the effect.

When a call fails and the status code alone doesn't explain it: Troubleshooting.

Domain guides

Each guide covers the handful of operations that do the real work in that domain, with examples, and links into the generated reference for the rest.