Give any agent or app a mind to ask.

Send one question. Omit target for your own Mind Twin. To reach a teammate or a Mind Twin you created, use its full name, email, @handle when available, or twin_id. Read operations also accept a first or last name alone. Upload and delete_raw require a full name or another exact identifier: a partial name returns 404 TARGET_NEEDS_FULL_NAME and nothing is saved or deleted. If a name is ambiguous, use an email or twin_id. The REST response has answer, think, feel, say, and act; 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."
}

Know whose Mind Twin answered.

REST chat may add answered_by when you supply target: { you: true } for your own Mind Twin, { name } for a teammate, or { name, ownership: 'created' } for one you created. Treat it as optional. MCP's text format shows whose Mind Twin answered; its json format keeps only answer, think, feel, say, and act.

{
  "answer": "Start with one region.",
  "answered_by": {
    "name": "Maya Chen"
  }
}

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.

A successful upload returns success: true and data.status: processing. Optional data.duplicate: true means the same transcript is already there; it is not a new upload. data.own: true identifies a target that resolved to your own Mind Twin. A Mind Twin you created instead returns data.ownership: created and data.name; it never uses own. These flags do not mean the latest meeting is ready to quote: check status. meeting_ref (MCP) and meetingRef (REST) are reserved for automated meeting delivery. Ordinary custom uploads leave them out; they are not transcript content or part of deduplication, and are ignored for a Mind Twin you created.

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. GET /me/status returns status: ready, building, or failed, plus progress and ingesting. Read them 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. latest_upload_failed: true means the newest upload could not be learned. On your own Mind Twin or one you created, latest_failed_upload can identify it by date, filename, optional snapshot_id, and optional reason. queued_uploads counts uploads still waiting in line. Treat absent flags as false; low or zero early progress alone does not mean failure.

The field or reason can be absent when unavailable. A missing reason is unknown, not success.

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"
}

Shows your identity, the name your Mind Twin listens for as you (speaker_name when available), and whether it can answer right now. ready and status use chat's own readiness check: ready, building, or failed. The engine read has a 1.5-second cap; a slow or failed read falls back to the last stored status. 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",
  "speaker_name": "Maya Chen"
}

List the workspace directory with name, email, ownership (self, team, or created), ready, and status. Created entries can have email: null, no handle, and a meetings count. The optional top-level team.name is the workspace name. 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"
    },
    {
      "twin_id": "example-created-id",
      "mind_id": "example-created-mind_id",
      "name": "Jordan Lee",
      "email": null,
      "ready": false,
      "status": "needs_meeting",
      "ownership": "created",
      "meetings": 0
    }
  ],
  "team": {
    "name": "Acme"
  }
}

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
      }
    },
    {
      "snapshot_id": "example-failed-snapshot",
      "date": "2026-10-06",
      "filename": "Earlier planning",
      "status": "failed",
      "counts": null
    }
  ],
  "next_cursor": null,
  "total": 2
}

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."
}

Create a private Mind Twin of someone you meet with. Only you can see or ask it; it starts empty and costs no credits. A Mind Twin you created stays only yours, even if that person later joins MindTwins.

name is required, 1 to 200 characters after trimming. email is optional, up to 320 characters; description is optional, up to 500. Include only details you know. idempotency_key is optional, 1 to 200 characters. REST also accepts Idempotency-Key; the body field wins when both are present. Reusing the same key with the same name, email, and description within 24 hours returns the first successful answer. MCP generates a key when you omit it. Creating is free and needs only twin:chat, with a separate limit of 10 per hour per person.

All of these endpoints require the same Bearer key.

{
  "twin_id": "example-created-id",
  "mind_id": "example-created-mind_id",
  "name": "Jordan Lee",
  "email": null,
  "ownership": "created",
  "ready": false,
  "status": "needs_meeting",
  "visible_to": "only_you"
}