Give any agent or app a mind to ask.

Send one question. Omit target to use your own Mind Twin. MCP also accepts a blank target; REST chat and upload reject an empty string. If a name matches more than one person, the API returns 422 AMBIGUOUS_TARGET; use their email. list_twins shows name (email) when names collide. The REST response is the bare answer, think, feel, say, act object; empty parts are omitted. format is MCP-only.

POST https://app.mindtwins.com/api/twin-mcp/chat
Authorization: Bearer $MINDTWINS_KEY
Content-Type: application/json

{
  "message": "What would make you reject this rollout?",
  "target": "Maya Chen"
}

{
  "answer": "I would reject a company-wide rollout without a contained pilot.",
  "think": "The upside is clear. The implementation risk is not.",
  "feel": "Interested, but exposed if adoption fails.",
  "say": "Show me one region working first.",
  "act": "Approve a 30-day pilot with a stop point."
}

Continue a conversation and attach text

REST chat accepts history: up to 20 earlier turns, each with role (user or assistant) and content. User content allows 800,000 UTF-16 code units; assistant content allows 100,000. Send the turns you want considered on each request. There is no conversation ID that restores earlier turns.

Use context for attached text: one string or up to 10 strings. Each item allows 100,000 UTF-16 code units and, after trimming and normalization, at most 51,200 UTF-8 bytes. Context is allowed on the current question and earlier user turns, never assistant turns. Extract text from PDFs or documents before sending it. The prepared current message plus context must fit 1,470,000 characters after escaping; a punctuation-heavy message can hit this limit before 800,000 input characters. The complete JSON body must also fit the hosting limit.

Requests accept Unicode text and have no language selector or published per-language guarantee. Test representative transcripts and questions in the languages your integration needs before rollout.

{
  "message": "How should we respond?",
  "context": [
    "Jordan Lee: Can we expand the pilot next week?"
  ],
  "history": [
    {
      "role": "user",
      "content": "What matters most for this launch?"
    },
    {
      "role": "assistant",
      "content": "A clear rollback plan."
    }
  ]
}

Recommended request budget: under 4,000,000 bytes for the complete UTF-8 JSON body. This is a conservative client budget, not an exact service maximum. Count the encoded body, including JSON escaping and metadata. Oversized requests can return a plain-text 413 FUNCTION_PAYLOAD_TOO_LARGE before the API runs. The MCP transcript schema limit does not override HTTP or downstream limits. REST has a larger application cap of 52,428,800 bytes for transcript plus segment text and 54,525,952 bytes for the raw JSON body; the public hosting limit applies first, so these are not usable upload sizes at this URL.

The MCP transcript limit is 10,000,000 characters at the schema level; request-body limits still apply.

Use the real meeting date in ISO 8601, from January 1, 2000 through 24 hours ahead of server time. Confirm the date for every transcript.

REST-only segments accepts up to 10,000 objects: text (required string), speaker (optional full name), startTime and endTime (optional nonnegative seconds). transcript and date remain required. When segments is supplied, it takes precedence over format normalization. Keep transcript and segments consistent; their combined text contributes to the size limit.

For format: agent-json, transcript is a string containing JSON, not a nested object. Serialize either an array of segments or an object with a segments array. Each segment uses text, speaker, startTime, and endTime; times are nonnegative seconds. Blank or non-string text is skipped, invalid timestamps are ignored, and only the first 10,000 usable segments are retained. Malformed JSON or no usable text returns 400 INVALID_TRANSCRIPT.

{
  "date": "2026-10-07",
  "format": "agent-json",
  "transcript": "{\"segments\":[{\"speaker\":\"Maya Chen\",\"text\":\"Start with a small pilot.\",\"startTime\":0,\"endTime\":4},{\"speaker\":\"Jordan Lee\",\"text\":\"We will review the results first.\",\"startTime\":4,\"endTime\":8}]}"
}

For a retry, resend the same transcript, exact date string, title, format, target, source, duration, and participants in the same order. Changing meeting details can save a second copy. Deduplication compares generated transcript content within the selected Mind Twin. A completed duplicate returns 200; queued or processing duplicates can also return 200 in workspaces with a build queue. ALREADY_PROCESSING means the same transcript is in progress: check status instead of uploading again. BUILD_IN_PROGRESS means this upload was not saved: wait for the current build, then retry. If an upload reply is lost, check status first and preserve the original payload for any retry.

POST https://app.mindtwins.com/api/twin-mcp/upload
Authorization: Bearer $MINDTWINS_KEY
Content-Type: application/json

{
  "date": "2026-10-07",
  "title": "Rollout planning",
  "format": "vtt",
  "transcript": "WEBVTT\n\n00:00:01.000 --> 00:00:05.000\n<v Maya Chen>I want to test one region before we commit to a full rollout.</v>\n\n00:00:05.000 --> 00:00:09.000\n<v Jordan Lee>What would you need to see before expanding?</v>\n\n00:00:09.000 --> 00:00:14.000\n<v Maya Chen>Four weeks of steady adoption and a clear way to stop if it slips.</v>",
  "target": "Maya Chen"
}

{
  "success": true,
  "data": {
    "status": "processing"
  }
}

Use ?target=Maya%20Chen for a teammate. Recommended client strategy: check status every 15 seconds, then every 30 to 60 seconds for longer builds. These intervals are guidance, not server requirements. Build time varies; use status rather than a fixed delay. No completion webhooks are available. Read ready, building, or failed together with the optional flags. needs_upload: true means upload a transcript instead of polling an empty Mind Twin. ready + hydrating: true means it can answer from previously learned material, but the latest upload is not available yet. ready + ingesting: true means a transcript is being folded in. Treat absent flags as false; low or zero early progress alone does not mean failure.

GET https://app.mindtwins.com/api/twin-mcp/me/status?target=Maya%20Chen
Authorization: Bearer $MINDTWINS_KEY

{
  "status": "building",
  "progress": 42,
  "ingesting": false
}

No key required. Use it for a simple service liveness check.

GET https://app.mindtwins.com/api/twin-mcp/health

{
  "status": "ok",
  "service": "twin-mcp",
  "timestamp": "2026-10-08T14:35:56.581Z"
}

Identify yourself. Use GET /me/status to check build readiness; the identity readiness flag is a lighter signal. Returns 404 NO_TWIN if you have no Mind Twin.

None.

All of these endpoints require the same Bearer key.

{
  "twin_id": "example-twin_id",
  "mind_id": "example-mind_id",
  "workspace_id": "example-workspace_id",
  "user_id": "example-user_id",
  "name": "Maya Chen",
  "email": "maya\u0040example.com",
  "handle": "maya",
  "ready": true,
  "status": "ready"
}

List the workspace directory with name, email, ownership (self or team), ready, and status. Listing does not guarantee target permission; use GET /me/status to check access and build readiness.

None. The response contains twins: [...].

All of these endpoints require the same Bearer key.

{
  "twins": [
    {
      "twin_id": "example-twin_id",
      "mind_id": "example-mind_id",
      "name": "Maya Chen",
      "email": "maya\u0040example.com",
      "handle": "maya",
      "ready": true,
      "status": "ready",
      "ownership": "self"
    }
  ]
}

Browse a Mind Twin's snapshots. The response contains snapshots, next_cursor, and total.

Query: target, cursor, limit (1 to 100; default 25).

All of these endpoints require the same Bearer key.

{
  "snapshots": [
    {
      "snapshot_id": "example-snapshot",
      "date": "2026-10-07",
      "filename": "Rollout planning",
      "status": "completed",
      "counts": {
        "data_points": 120,
        "key_topics": 4,
        "findings": 8
      }
    }
  ],
  "next_cursor": null,
  "total": 1
}

Read one snapshot's summaries and counts. Raw psychometric records are withheld; the profile can include derived scores and confidence labels.

Path: id. Query: detail (concise or detailed), target.

Findings and Mindsets are learned outputs associated with a snapshot. Browse snapshots, then inspect a snapshot by its ID. The API does not provide a combined per-person Findings or Mindsets view.

All of these endpoints require the same Bearer key.

{
  "ready": true,
  "snapshot_id": "example-snapshot",
  "date": "2026-10-07",
  "filename": "Rollout planning",
  "status": "completed",
  "counts": {
    "data_points": 120,
    "key_topics": 4,
    "findings": 8
  },
  "summary": {
    "disposition": null,
    "synthesis": [
      {
        "ticker": "SYN-01",
        "label": "Decision style",
        "value": "Prefers evidence before expanding a rollout."
      }
    ],
    "categories": [
      {
        "index": "01",
        "title": "Decision-making",
        "items": [
          {
            "subIndex": "01.1",
            "label": "Trade-offs",
            "value": "Balances speed with a clear rollback plan."
          }
        ]
      }
    ]
  },
  "profile": {
    "twin": "Maya Chen",
    "proceedings": 1,
    "findings": 8,
    "points": 120,
    "domainSummary": null,
    "coreProfile": null,
    "buckets": []
  }
}

Preview removal without confirm, then permanently remove raw material with confirm: true and the dry run's expected_count. A stale count returns 409 PRECONDITION_FAILED. The snapshot counts and Mind Twin remain; no rebuild.

Path: id. JSON body: confirm, dry_run, expected_count, idempotency_key, target. dry_run: true overrides confirm. Confirmation requires the latest expected_count. The idempotency cache lasts 10 minutes per server instance; do not rely on it across retries to a different instance. Reconcile a lost response with a fresh dry run.

delete_raw removes one transcript from the Mind Twin's recall store and browse list. It does not delete the snapshot or Mind Twin, erase learned outputs, or trigger a rebuild. The public integration API has no Mind Twin deletion, snapshot deletion, or export endpoint.

All of these endpoints require the same Bearer key.

{
  "dry_run": true,
  "snapshot_id": "example-snapshot",
  "found": true,
  "would_delete": {
    "mind_sync_rows": 1
  },
  "expected_count": 1,
  "message": "This is a dry run. No data has been removed."
}