Raconte for developers

Raconte lets an AI agent run voice interviews with real people and get the transcripts back. The agent creates an interview from a prompt. Raconte emails the link to each person, or returns one link to share. An AI interviewer holds the conversation and asks follow-up questions. Once the call ends, the agent reads the full transcript, a summary and the sentiment of each answer. Interviews and invitations are exposed over a REST API, an MCP server, a typed SDK and a CLI, which all take the same organization API key.

What the API does and does not do

TaskSupportedHow
Create an interview from a promptYesPOST /v1/interviews, the create-interview MCP tool or raconte interviews create
Send the link to real peopleYesPass invitees and Raconte emails each one, or leave them out and share the returned URL yourself
Get the transcript, the summary and the sentiment of each answerYesOn request over REST and MCP, or pushed by the interview.completed webhook
Get the audioYes, over RESTA presigned URL for the recording of each message
Know when an interview starts or endsYesThe interview.started and interview.completed webhooks
Recruit participantsNoYou bring the people: your users, your customers, a panel you already work with
Simulate participantsNoEvery answer comes from a real person speaking
Produce a report across several interviewsNoYour agent reads the transcripts over the API or MCP and does the comparison

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.

A key carries the whole public surface, listed as interviews:read, interviews:write, invitations:read and invitations:write in the protected resource metadata. Those names describe what a call can do. You cannot request them one by one, so there is no narrower key to ask for.

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 (RFC 9728), so one failed request is enough for an agent to find out how to authenticate. The same flow is written out in prose at 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

ResourceURL
API index (base URL)api.raconte.ai
OpenAPI 3.1 specificationraconte.ai/openapi.json
Interactive reference/en/docs/api-reference
MCP server card/.well-known/mcp/server-card.json
Site index for LLMsraconte.ai/llms.txt
Agent skill for the CLIraconte.ai/skill.md
Authentication walkthroughraconte.ai/auth.md
Protected resource metadata (RFC 9728)api.raconte.ai/.well-known/oauth-protected-resource
API catalog (RFC 9727)/.well-known/api-catalog
Agentic Resource Discovery catalog/.well-known/ai-catalog.json
Agent Skills index/.well-known/agent-skills/index.json
Pricing, machine-readableraconte.ai/pricing.md

Every page of the Raconte documentation 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, /docs/llms.txt, /guides/llms.txt and /blog/llms.txt.

The four surfaces

Quickstart

Terminal window
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' },
})

From n8n or Make

n8n and Make reach Raconte through their standard HTTP request and webhook steps. A typical workflow uses one of each:

  1. An HTTP request step calls POST /v1/interviews with the prompt and the invitees, sending the API key as a bearer token. Raconte emails each person their link.
  2. A webhook trigger receives interview.completed and hands the transcript and the summary to the next steps, which can add a note to the CRM, post a Slack message or add a row to a spreadsheet.

Raconte delivers each webhook in a single attempt, with no retry if your endpoint fails, so a workflow that must not miss an interview should also list the interview’s invitations on a schedule and check their status.

When an n8n workflow runs an AI agent, the MCP Client Tool node connects that agent to the MCP server, so the agent creates interviews and reads transcripts on its own. Configure the node like any MCP client, with the endpoint URL and the API key header. The agent then takes requests in plain language for every step of an interview, from creating it to reading the transcript.

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. Every organization also 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. 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. The retirement date is announced on this page. Both headers are declared on every response in the specification, so a client can detect them automatically.

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, ask for an Enterprise quote with the number of interviews you expect per month and their languages.