Made in 10Docs
GuidesAPI

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

Base URL
https://talk.madein10.com/v1

Every request sends a secret key as Authorization: Bearer sk_live_… (or sk_test_…). See Authentication.

Your first request
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 (400 invalid_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 PATCH with only the fields to change. Attaching documents, guardrails, pronunciations or tools to a character is a PUT of 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.json
  • https://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.

Where next

On this page