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 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:

curl https://api.raconte.ai/v1/interviews \
  -H "Authorization: Bearer YOUR_API_KEY"

An x-api-key: YOUR_API_KEY header is also accepted.

Machine-readable entry points

Every documentation page also has a markdown twin: append .md to its URL, or send Accept: text/markdown.

The four surfaces

• REST 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: six tools over Streamable HTTP at https://api.raconte.ai/api/mcp, so Claude, Cursor, Opencode and other MCP clients operate the product natively. The setup guide has the per-client configuration.
• Webhooks: a signed POST to your endpoint when an interview starts or completes, to push transcripts into your own systems.
• SDK and 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

npm install -g @raconte/cli
export 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, so a client can throttle itself without guessing:

RateLimit-Policy: 300;w=60
RateLimit-Limit: 300
RateLimit-Remaining: 297
RateLimit-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 and RFC 8594) for at least six months before the endpoint stops answering, and the date is announced on this page.

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 lists the statuses each operation can return.

Getting help

Write to contact@raconte.ai with the id of the interview or invitation involved. For volume, white-label, SSO or an SLA, the contact page has the details worth sending.