--- title: "Developers | Raconte" description: "Everything needed to build on Raconte: API keys, OpenAPI spec, REST API, MCP server, webhooks, SDK, CLI, rate limits and versioning policy." url: "https://raconte.ai/en/developers" --- # Raconte for developers Raconte is a product you can drive from code. Interviews and invitations are exposed over a REST API, an MCP server, a typed SDK and a CLI, all against the same surface and the same organization API key. ## Get a key Create an organization API key from [Settings → API](/settings/api) in the app. The full value is shown once, at creation. Every key is scoped to one organization: requests only ever see that organization’s interviews, invitations and transcripts. Pass it as a bearer token: Terminal window ``` curl https://api.raconte.ai/v1/interviews \ -H "Authorization: Bearer YOUR_API_KEY" ``` An `x-api-key: YOUR_API_KEY` header is also accepted. A call without a key answers `401` with a `WWW-Authenticate` header naming the [protected resource metadata](https://api.raconte.ai/.well-known/oauth-protected-resource) ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html)), so one failed request is enough for an agent to find out how to authenticate. The prose version of the same thing is [auth.md](/auth.md): where a key comes from, how to send it, what each error means, how to revoke. Raconte issues API keys rather than running an OAuth authorization server, so there is no dynamic client registration: a person creates the key and hands it over. ## Machine-readable entry points Resource URL OpenAPI 3.1 specification [raconte.ai/openapi.json](/openapi.json) Interactive reference [/en/docs/api-reference](/en/docs/api-reference) MCP server card [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json) Site index for LLMs [raconte.ai/llms.txt](/llms.txt) Agent skill for the CLI [raconte.ai/skill.md](/skill.md) Authentication walkthrough [raconte.ai/auth.md](/auth.md) Protected resource metadata (RFC 9728) [api.raconte.ai/.well-known/oauth-protected-resource](https://api.raconte.ai/.well-known/oauth-protected-resource) API catalog (RFC 9727) [/.well-known/api-catalog](/.well-known/api-catalog) Agentic Resource Discovery catalog [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) Agent Skills index [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json) Pricing, machine-readable [raconte.ai/pricing.md](/pricing.md) Every documentation page also has a markdown twin: append `.md` to its URL, or send `Accept: text/markdown`. When the whole-site index is more context than you need, four scoped ones cover a single area: [/developers/llms.txt](/developers/llms.txt), [/docs/llms.txt](/docs/llms.txt), [/guides/llms.txt](/guides/llms.txt) and [/blog/llms.txt](/blog/llms.txt). ## The four surfaces * **[REST API](/en/docs/api)**: 26 operations over HTTP for interviews and invitations, including transcripts, activity logs and presigned audio URLs. Base URL `https://api.raconte.ai`, every path prefixed with `/v1`. * **[MCP server](/en/docs/mcp)**: eight tools over Streamable HTTP at `https://api.raconte.ai/api/mcp`, so Claude, Cursor, Opencode and other MCP clients operate the product natively. The handshake and `tools/list` are open, so a client can read the catalogue before it holds a key. The [setup guide](/en/guides/mcp-setup) has the per-client configuration. * **[Webhooks](/en/docs/webhooks)**: a signed POST to your endpoint when an interview starts or completes, to push transcripts into your own systems. * **[SDK](/en/docs/sdk) and [CLI](/en/docs/cli)**: `@raconte/node-sdk` for TypeScript and Node applications, `@raconte/cli` for terminals, scripts and AI agents. The SDK is generated from the specification above, so it never drifts from the API. ## Quickstart Terminal window ``` npm install -g @raconte/cliexport RACONTE_API_KEY="YOUR_API_KEY" raconte interviews create \ --prompt "Ask about the onboarding: what was confusing, what was missing" \ --email jane@example.com ``` The command returns the created interview and its invitations as JSON, including the link to share. From TypeScript, the same call goes through the SDK: ``` import { createRaconteClient, interviewsControllerCreate } from '@raconte/node-sdk' const client = createRaconteClient({ apiKey: process.env.RACONTE_API_KEY! }) const { data, error } = await interviewsControllerCreate({ client, body: { prompt: 'Ask about the onboarding: what was confusing, what was missing' },}) ``` ## Testing without spending minutes There is no separate sandbox host: the API runs against your real organization, and the free plan covers the exploration. Creating interviews, invitations and links costs nothing, since billing only counts active interview minutes, and every organization gets 60 free minutes per month. Create a throwaway interview, run one call against it yourself, then archive it. For a dry run with no call at all, create an interview without `invitees`. You get a READY invitation and its shareable URL, and nothing is billed until someone talks. ## Rate limits Every response carries the [IETF RateLimit header fields](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/), so a client can throttle itself without guessing: ``` RateLimit-Policy: 300;w=60RateLimit-Limit: 300RateLimit-Remaining: 297RateLimit-Reset: 42 ``` The quota is 300 requests per minute per API key. Past it the API answers `429` with a `Retry-After` header giving the seconds to wait. Retry after that delay rather than immediately. ## Versioning and deprecation Every path is prefixed with the API version: `https://api.raconte.ai/v1/interviews`. The specification, the SDK and the CLI all use it, so an integration built on any of them is versioned without any work on your side. A breaking change gets a new version segment rather than a change to `v1`. When a version is retired, the affected responses carry the `Deprecation` and `Sunset` headers ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html) and [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)) for at least six months before the endpoint stops answering, and the date is announced on this page. Both headers are declared on every response in the [specification](/openapi.json), so a client can watch for them without parsing this paragraph. ## Errors Errors come back as JSON, never as an HTML page. Most of them carry the HTTP status, a short `error` label and a human-readable `message`: ``` { "statusCode": 404, "error": "Not Found", "message": "Interview not found"} ``` A body or parameter that fails validation answers `400` with the field-level detail instead, one entry per rejected value: ``` { "statusCode": 400, "timestamp": "2026-08-22T14:30:47.304Z", "path": "/v1/interviews", "errors": [ { "path": ["prompt"], "code": "too_small", "message": "Too small: expected string to have >=10 characters" } ]} ``` Both shapes are typed in the specification, so the SDK and any generated client know what to expect. The [interactive reference](/en/docs/api-reference) lists the statuses each operation can return. ## Getting help Write to [contact@raconte.ai](mailto:contact@raconte.ai) with the id of the interview or invitation involved. For volume, white-label, SSO or an SLA, the [contact page](/en/contact) has the details worth sending.