Documentation

API reference

The full public v1 surface is three endpoints. Base URL for all of them: https://mcp.mnemix.ai. Every request needs a bearer token:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

POST /v1/recall_and_enrich

The hot path. Call it once, before the agent's first turn. Auto-creates the caller on a miss, recalls same-number memory, and fires real-world enrichment for cold and returning callers.

Request body:

Field	Type	Required	Notes
`phone_number`	string	yes	Any format; normalized to E.164 server-side.
`trigger`	`"ringing"` \| `"answered"`	no	When in the call lifecycle this fired.
`session_id`	string	no	Correlates this recall with the matching `calls/end` write-back.
`agent_id`	string	no	Which agent/assistant is handling the call, if you run more than one.
`metadata`	object	no	Arbitrary key-value passthrough, stored with the interaction.

curl -sS -X POST https://mcp.mnemix.ai/v1/recall_and_enrich \
  -H "Authorization: Bearer $MNEMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "trigger": "answered",
    "session_id": "call_abc123"
  }'

Response — 200 OK:

{
  "trace_id": "trace_...",
  "known": true,
  "caller": {
    "name": "Mike Reynolds",
    "first_seen_ms": 1750000000000,
    "last_seen_ms": 1751000000000,
    "total_calls": 3,
    "tags": ["fleet", "commercial"],
    "custom_attributes": {}
  },
  "memory": {
    "summary": "Repeat customer, 3 calls over 2 months. Fleet account.",
    "recent_calls": [
      {
        "call_id": "int_...",
        "started_at_ms": 1750900000000,
        "duration_s": 92,
        "summary": "Confirmed brake inspection for Thursday",
        "outcome": "appointment_booked"
      }
    ]
  },
  "enrichment": {
    "person": { "name": "Mike Reynolds", "title": null, "company": null },
    "company": null,
    "phone": { "carrier": "Verizon", "line_type": "mobile" }
  },
  "timing_ms": { "total": "<measured>", "memory_ms": "<measured>", "enrichment_ms": "<measured>", "cache_hit": true },
  "freshness": { "memory_age_ms": null, "enrichment_age_ms": null }
}

timing_ms and freshness are real measured fields on every response — not published benchmarks. A first-time caller returns known: false with enrichment populated instead of memory; a Mnemix-side degradation returns the same shape with degraded: true and empty defaults, so your integration never has to special-case a failure mode — it always gets a well-formed object back.

POST /v1/calls/end

The write-back. Record what happened so the next call starts warmer. Summarization runs in the background — this call returns immediately.

Request body:

Field	Type	Required	Notes
`session_id`	string	yes	Must match the `session_id` from the paired `recall_and_enrich` call.
`phone_number`	string	yes	Same caller.
`transcript`	array of `{role, text, ts_ms}`	yes	`role` is `"user"` or `"agent"`. Not a raw string.
`duration_s`	number	yes	Call length in seconds, ≥ 0.
`outcome`	string	yes	One of `appointment_booked`, `quote_given`, `callback_requested`, `no_answer`, `other`.
`agent_metadata`	object	no	Arbitrary key-value passthrough.

curl -sS -X POST https://mcp.mnemix.ai/v1/calls/end \
  -H "Authorization: Bearer $MNEMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "call_abc123",
    "phone_number": "+15551234567",
    "transcript": [
      { "role": "agent", "text": "Thanks for calling, how can I help?", "ts_ms": 0 },
      { "role": "user", "text": "I need to confirm Thursday.", "ts_ms": 3200 }
    ],
    "duration_s": 92,
    "outcome": "appointment_booked"
  }'

Response — 204 No Content. No body. Mnemix summarizes in the background; the next recall_and_enrich for this caller reflects it.

GET /v1/caller/

Read-only profile fetch. No side effects — doesn't trigger enrichment, doesn't create a contact on a miss.

curl -sS https://mcp.mnemix.ai/v1/caller/+15551234567 \
  -H "Authorization: Bearer $MNEMIX_API_KEY"

Response — 200 OK:

{
  "name": "Mike Reynolds",
  "first_seen_ms": 1750000000000,
  "last_seen_ms": 1751000000000,
  "total_calls": 3,
  "tags": ["fleet", "commercial"],
  "custom_attributes": {}
}

404 if the number has never called — this endpoint never auto-creates. Use recall_and_enrich for that.

Errors

Every non-2xx response carries a machine-readable code:

{ "error": { "code": "validation_error", "message": "..." } }

Status	Code	Meaning
`400`	`bad_request`	Malformed input — e.g. an unparseable phone number.
`401`	`unauthorized`	Missing or invalid bearer token.
`404`	`not_found`	`GET /v1/caller/{phone_number}` on an unknown caller.
`422`	`validation_error`	Request body fails schema validation.
`429`	`rate_limited`	Token bucket exhausted; back off and retry.

Machine-readable spec

The same three endpoints, as OpenAPI: /.well-known/openapi.json. Codegen a typed client directly from it — the spec mirrors the same request schemas the API enforces.

Next steps

MCP server — the same three primitives as native tools, no HTTP client needed.
What is caller memory? — the concept behind recall_and_enrich.