--- type: page title: Developers description: "How to reach Falcata's REST API and MCP server, authenticate, and let an agent discover what the platform can do." resource: https://www.falcata.io/developers canonical: https://www.falcata.io/developers timestamp: "2026-08-23T21:56:29.666Z" last-updated: "2026-08-25T23:05:57.081Z" access: public status: published nodeId: "24fddf92-3cf2-4304-bafa-aa7d8a387f21" --- Falcata products run on Furnace, our own platform with one authenticated API surface. The same operations are available over REST and over the Model Context Protocol, so a script and an AI agent reach the platform the same way — and the API you would use is the API our own apps use. ## Start here - **OpenAPI 3.1 specification:** [api.falcata.io/api/v1/openapi.json](https://api.falcata.io/api/v1/openapi.json) — 280 operations across content, tasks, workflows, notifications, media, analytics, and access control. Generate a client from it rather than hand-writing requests. - **REST base URL:** `https://api.falcata.io/api/v1`. The base URL returns an index of every discovery document listed on this page. - **MCP server:** `https://api.falcata.io/mcp`, Streamable HTTP transport. `initialize`, `tools/list`, and `resources/*` answer without credentials, so a client can read the full tool catalogue before anyone signs in. `tools/call` requires a token. - **Documentation:** the dedicated docs site is live at [docs.falcata.dev](https://docs.falcata.dev) — quickstarts, authentication walkthroughs, per-domain API guides, and every page also served as markdown. ## Authenticate [auth.md](/auth.md) is the full walkthrough. In short, three ways to get a credential: - **Personal access token** — for a script or a machine you control. Tokens begin with `fpat_` and can be scoped to read-only. - **Device flow** — for a CLI or anything that cannot receive a browser redirect. - **Authorization code with PKCE** — for an application that can. Send the credential as `Authorization: Bearer `. Endpoints that need a credential and do not get one answer `401` with a `WWW-Authenticate` header pointing at the metadata an OAuth client needs, so discovery costs one request. Two layers decide what a call may do. The token carries `api:read` or `api:write`; per-namespace roles then decide which resources it may touch. A token can never exceed the permissions of the person who created it. ## Limits and retries Personal access tokens are limited to 600 requests per minute, with 100 available in a burst. Responses that pass through the limiter carry `RateLimit` and `RateLimit-Policy` headers; an exhausted caller gets `429` and a `Retry-After`. Writes are safe to retry: send an `Idempotency-Key` header and a retried write replays the original response instead of executing twice. The OpenAPI specification documents the header on every write operation. ## For agents Every Falcata site publishes machine-readable descriptions of itself: - `/llms.txt` — an index of the public pages and agent surfaces - `/llms-full.txt` — the same content as full text - `/.well-known/ai-catalog.json` — the catalogue of APIs, MCP servers, and skills this domain offers - `/.well-known/agent-skills/index.json` — skills describing when to use those surfaces and how - `/.well-known/mcp/server-card.json` — the MCP server's identity and tools, readable before opening a connection - `/.well-known/api-catalog` — the API catalogue, per RFC 9727 Public pages are also served as markdown: append `.md` to a page URL, or send `Accept: text/markdown`. ## Questions developers ask **Which credential should I use?** A personal access token for a script or a machine you control; the device flow for a CLI or an agent that cannot receive a browser redirect; authorization code with PKCE for an application that can. [auth.md](/auth.md) walks through each. **Can an agent explore the API before anyone signs in?** Yes. The OpenAPI specification, the MCP `initialize`, `tools/list`, and `resources/*` methods, and every discovery document on this page answer without credentials. Only `tools/call` and the REST operations themselves need a token. **What are the rate limits?** 600 requests per minute per personal access token, with 100 available in a burst. Responses carry `RateLimit` and `RateLimit-Policy` headers; past the limit you get `429` and a `Retry-After`. **Is it safe to retry a write?** Yes, if you send an `Idempotency-Key`. A retried write replays the original response instead of executing twice; while the first attempt is still running you get `409` with `code: idempotency_in_progress` and a `Retry-After`. **Is there a sandbox?** Not as a separate environment. For safe exploration, scope a personal access token to read-only; the read surface is the same one our products use. **Where is the documentation?** At [docs.falcata.dev](https://docs.falcata.dev) — guides and walkthroughs for every public surface, with the OpenAPI specification as the generated reference alongside it. ## Getting access If you have a Falcata account, the device flow described in [auth.md](/auth.md) signs a CLI or agent in with nothing more than a browser approval; what the credential can reach is governed by the same roles you hold in the product. For a production integration, or access beyond what your account already allows, [tell us what you want to build](/contact) and we will set it up with you.