The API
What /v1 is for, how to call it, and the conventions every endpoint follows.
The /v1 API is for your servers. With it you make characters (a name, instructions, knowledge, one of our faces and a voice), start live calls with them, send them into meetings, and hear what happened through webhooks. Website deployments are made in the dashboard or through the MCP server; they aren't on /v1 yet.
Placeholder names
The product has no name yet. "Acme API", the acme-webhooks/1 user agent and the address talk.madein10.com are placeholders: they will change when it has one.
Base URL
https://talk.madein10.com/v1Every request sends a secret key as Authorization: Bearer sk_live_… (or sk_test_…). See Authentication.
curl https://talk.madein10.com/v1/characters \
-H "Authorization: Bearer $ACME_SECRET_KEY"Live and test keys
A live key (sk_live_…) runs real calls, charged at your character's tier price. A test key (sk_test_…) runs real calls that are never charged: at most 60 seconds each, and 20 calls per organization in any 24 hours. Each key sees its own env only: a test key lists and reads only test calls and meetings and sees only test webhook endpoints, memories and analytics, and a live key the live ones. Characters and their knowledge are shared by both. See Authentication.
Conventions
- JSON in, JSON out. Send
Content-Type: application/json. A JSON body may be at most 2 MB (see Limits). Every body refuses fields it doesn't know (400invalid_json), so a typo never goes unnoticed. - Ids are a prefix and 20 random characters:
chr_a character,call_a call,mtg_a meeting,whe_a webhook endpoint,evt_an event,whd_a delivery,doc_a document,grd_a guardrail set,prn_a pronunciation dictionary,tool_a tool,tcl_one call of a tool,mem_a remembered fact,req_a custom-character request,key_a key,vce_a cloned voice,mcps_an MCP server,ico_a launcher icon. - Money is US dollars as a number, in fields ending
_usd. A call that failed, never connected or never played a reply costs nothing. - Times are unix seconds, UTC, in fields ending
_unix. - Lists answer
{ "data": [...] }. A delete answers{ "id": "…", "deleted": true }. - Changes are
PATCHwith only the fields to change. Attaching documents, guardrails, pronunciations or tools to a character is aPUTof the whole ordered list. - Errors always have one shape:
{ "error": { "code": "…", "message": "…" } }. See Errors.
Pagination
Lists that can grow long (calls, meetings, an endpoint's deliveries, memories) are newest first and take limit and before. To get the next page, send before set to the last item's sort time (created_unix, or last_used_unix for memories). has_more says whether there is more.
Times are whole seconds, so an item made in the same second as a page's last one can repeat on the next page, or be missed. Dedupe by id.
The other lists answer everything at once. They are small: at most 200 documents, 100 guardrail sets, 50 dictionaries, 50 tools, 10 MCP servers, 10 webhook endpoints and 5 cloned voices.
The OpenAPI file
The reference in these docs is made from our OpenAPI 3.1 file. Use it to generate a client, or to import the API into your tools:
https://talk.madein10.com/docs/openapi.jsonhttps://talk.madein10.com/docs/openapi.yaml
It has every /v1 endpoint and every webhook event.
A call, end to end
Start it from your server
POST /v1/calls with a character. It answers ws_url for the person's browser or app, and events_url for your server. See Calls.
The browser connects to the call's sound
Hand ws_url (or ws) to the page. The browser connects within 120 seconds and streams its microphone. Our browser SDK does all of it; the protocol is on The sound socket.
Your server listens and steers
Keep events_url on your server: it streams the transcript as it happens, and takes say, context and end. See Live events and control.
Webhooks tell you the rest
call.started, call.ended (with the charge and the transcript), call.analyzed and more arrive at your endpoint, signed, even when nothing is connected. See Webhooks.
The call is the truth
GET /v1/calls/{call_id} has the transcript, the charge, the analysis, the tools used and the recording. When an event and it disagree, it is right.