Developers
Falcata

Developers

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(opens in a new tab) — 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(opens in a new tab) — quickstarts, authentication walkthroughs, per-domain API guides, and every page also served as markdown.

Authenticate

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 <token>. 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 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(opens in a new tab) — 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 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 and we will set it up with you.