{ "openapi": "3.1.0", "info": { "title": "MindTwins integration API", "version": "2026-10-08", "description": "Documentation revision, not an API version. Custom integrations only. Installer and session-management routes are excluded. Source verified against Rainmaker 1a92f78ee69bcbcbfbce2c182021eeb49db95543. Examples use illustrative values." }, "servers": [ { "url": "https://app.mindtwins.com/api/twin-mcp" } ], "security": [ { "bearerKey": [] } ], "paths": { "/health": { "get": { "operationId": "health", "summary": "health", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } }, "security": [] } }, "/me": { "get": { "operationId": "whoami", "summary": "whoami", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Identity" }, "example": { "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@example.com", "handle": "maya", "ready": true, "status": "ready" } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/twins": { "get": { "operationId": "listTwins", "summary": "listTwins", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Directory" }, "example": { "twins": [ { "twin_id": "example-twin_id", "mind_id": "example-mind_id", "name": "Maya Chen", "email": "maya@example.com", "handle": "maya", "ready": true, "status": "ready", "ownership": "self" } ] } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "Workspace directory, not an authorization guarantee. Target resolution separately checks scope and the key allowlist. Use /me/status for build readiness; directory ready is a lighter signal." } }, "/chat": { "post": { "operationId": "chat", "summary": "chat", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatResponse" } } } }, "400": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } }, "description": "Caller-supplied history, at most 20 turns. context is text, not binary file upload, and is accepted only on user turns. No server conversation ID. Allow 600 seconds client timeout; server execution budget is 540 seconds." } }, "/upload": { "post": { "operationId": "upload", "summary": "upload", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResponse" } } } }, "400": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } } }, "description": "Keep the encoded JSON request below the recommended 4,000,000-byte budget. Hosting limits apply before the larger application limits. transcript remains required with segments; segments bypass format normalization." } }, "/me/status": { "get": { "operationId": "status", "summary": "status", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "target", "in": "query", "required": false, "schema": { "type": "string" } } ] } }, "/snapshots": { "get": { "operationId": "listSnapshots", "summary": "listSnapshots", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotList" }, "example": { "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 } } } }, "400": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "target", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ] } }, "/snapshots/{id}": { "get": { "operationId": "getSnapshot", "summary": "getSnapshot", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotDetail" }, "example": { "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": [] } } } } }, "400": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "concise", "detailed" ], "default": "detailed" } } ] } }, "/snapshots/{id}/raw": { "delete": { "operationId": "deleteRaw", "summary": "deleteRaw", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" }, "example": { "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." } } } }, "400": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Reset-Minute": { "schema": { "type": "string", "format": "date-time" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Hour": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" }, "description": "Returned on a rate-limit refusal; not guaranteed on successful responses." } } }, "500": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "See the error reference. Codes vary by operation; some authentication errors omit code. Hosting 413 responses can be plain text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRequest" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "description": "Dry run by default. To remove recall rows, send confirm:true and the latest expected_count; dry_run:true overrides confirm. Idempotency cache is per server instance for ten minutes, not a durable guarantee. Engine snapshots and learned profiles remain." } } }, "components": { "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer", "description": "MindTwins developer key. Keep it server-side." } }, "schemas": { "Context": { "oneOf": [ { "type": "string", "maxLength": 100000 }, { "type": "array", "items": { "type": "string", "maxLength": 100000 }, "maxItems": 10 } ], "description": "Trimmed and normalized text. Each item is limited to 51,200 UTF-8 bytes. Blank items are ignored." }, "Segment": { "type": "object", "properties": { "speaker": { "type": "string" }, "text": { "type": "string" }, "startTime": { "type": "number", "minimum": 0 }, "endTime": { "type": "number", "minimum": 0 } }, "required": [ "text" ] }, "ChatRequest": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 800000, "description": "UTF-16 code units. Prepared message plus current context must also fit 1,470,000 characters after XML escaping." }, "target": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Omit for your own Mind Twin. A teammate requires twin:upload, team visibility, the same workspace, and any key target allowlist." }, "context": { "$ref": "#/components/schemas/Context" }, "history": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "role": { "const": "user" }, "content": { "type": "string", "minLength": 1, "maxLength": 800000 }, "context": { "$ref": "#/components/schemas/Context" } }, "required": [ "role", "content" ] }, { "type": "object", "properties": { "role": { "const": "assistant" }, "content": { "type": "string", "minLength": 1, "maxLength": 100000 } }, "required": [ "role", "content" ], "not": { "required": [ "context" ] } } ] }, "maxItems": 20 } }, "required": [ "message" ] }, "ChatResponse": { "type": "object", "properties": { "answer": { "type": "string" }, "think": { "type": "string" }, "feel": { "type": "string" }, "say": { "type": "string" }, "act": { "type": "string" } }, "required": [ "answer" ] }, "UploadRequest": { "type": "object", "properties": { "transcript": { "type": "string", "minLength": 1, "maxLength": 52428800 }, "date": { "type": "string", "minLength": 1, "description": "Use ISO 8601, from 2000-01-01 through 24 hours ahead of server time." }, "title": { "type": "string", "maxLength": 500 }, "format": { "enum": [ "vtt", "srt", "text", "agent-json" ] }, "participants": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "source": { "enum": [ "fathom", "zoom", "gong", "google_meet", "fireflies", "microsoft_teams", "manual", "sybill", "affinity_notetaker", "granola", "raw_import" ] }, "duration": { "type": "number", "minimum": 0 }, "selfSpeaker": { "type": "string", "maxLength": 200 }, "target": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Omit for your own Mind Twin. A teammate requires twin:upload, team visibility, the same workspace, and any key target allowlist." }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" }, "maxItems": 10000 } }, "required": [ "transcript", "date" ] }, "UploadResponse": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "status": { "const": "processing" } }, "required": [ "status" ] } }, "required": [ "success", "data" ] }, "Identity": { "type": "object", "properties": { "twin_id": { "type": "string" }, "mind_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "handle": { "type": "string" }, "ready": { "type": "boolean" }, "status": { "enum": [ "ready", "building" ] }, "workspace_id": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "twin_id", "mind_id", "name", "email", "handle", "ready", "status", "workspace_id", "user_id" ] }, "DirectoryEntry": { "type": "object", "properties": { "twin_id": { "type": "string" }, "mind_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "handle": { "type": "string" }, "ready": { "type": "boolean" }, "status": { "enum": [ "ready", "building" ] }, "ownership": { "enum": [ "self", "team" ] } }, "required": [ "twin_id", "mind_id", "name", "email", "handle", "ready", "status", "ownership" ] }, "Directory": { "type": "object", "properties": { "twins": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryEntry" } } }, "required": [ "twins" ] }, "Status": { "type": "object", "properties": { "status": { "enum": [ "building", "ready", "failed" ] }, "progress": { "type": "number", "minimum": 0, "maximum": 100 }, "ingesting": { "type": "boolean" }, "hydrating": { "const": true }, "needs_upload": { "const": true } }, "required": [ "status", "progress", "ingesting" ] }, "Health": { "type": "object", "properties": { "status": { "const": "ok" }, "service": { "const": "twin-mcp" }, "timestamp": { "type": "string", "format": "date-time" } }, "required": [ "status", "service", "timestamp" ] }, "Counts": { "type": "object", "properties": { "data_points": { "type": "number" }, "key_topics": { "type": "number" }, "findings": { "type": "number" } }, "required": [ "data_points", "key_topics", "findings" ] }, "SnapshotRow": { "type": "object", "properties": { "snapshot_id": { "type": "string" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filename": { "type": "string" }, "status": { "type": "string" }, "counts": { "anyOf": [ { "$ref": "#/components/schemas/Counts" }, { "type": "null" } ] } }, "required": [ "snapshot_id", "date", "filename", "status", "counts" ] }, "SnapshotList": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "$ref": "#/components/schemas/SnapshotRow" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "type": "number" }, "message": { "type": "string" } }, "required": [ "snapshots", "next_cursor", "total" ] }, "Findings": { "type": "object", "properties": { "disposition": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "synthesis": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "ticker", "label", "value" ] } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "string" }, "title": { "type": "string" }, "blurb": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "subIndex": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "subIndex", "label", "value" ] } } }, "required": [ "index", "title", "items" ] } } }, "required": [ "disposition", "synthesis", "categories" ] }, "Attribute": { "type": "object", "properties": { "name": { "type": "string" }, "score": { "type": "number" }, "signal": { "type": "number" }, "confidence": { "enum": [ "Very High", "High", "Medium", "Low" ] }, "snapshot": { "type": "string" }, "description": { "type": "string" }, "howApplies": { "type": "string" }, "behavior": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cognition": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emotion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "action", "cognition", "emotion" ] } }, "required": [ "name", "score", "signal", "confidence", "snapshot", "description", "howApplies", "behavior" ] }, "Mindsets": { "type": "object", "properties": { "twin": { "type": "string" }, "proceedings": { "type": "number" }, "findings": { "type": "number" }, "points": { "type": "number" }, "domainSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "coreProfile": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "icon": { "type": "string" }, "attrs": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } } }, "required": [ "name", "icon", "attrs" ] } } }, "required": [ "twin", "proceedings", "findings", "points", "domainSummary", "coreProfile", "buckets" ] }, "SnapshotDetail": { "oneOf": [ { "type": "object", "properties": { "ready": { "const": false }, "status": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ready", "status", "message" ] }, { "type": "object", "properties": { "ready": { "const": true }, "snapshot_id": { "type": "string" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filename": { "type": "string" }, "status": { "type": "string" }, "counts": { "anyOf": [ { "$ref": "#/components/schemas/Counts" }, { "type": "null" } ] }, "summary": { "anyOf": [ { "$ref": "#/components/schemas/Findings" }, { "type": "null" } ] }, "profile": { "anyOf": [ { "$ref": "#/components/schemas/Mindsets" }, { "type": "null" } ] } }, "required": [ "ready", "snapshot_id", "date", "filename", "status", "counts", "summary", "profile" ] } ] }, "DeleteRequest": { "type": "object", "properties": { "confirm": { "type": "boolean" }, "dry_run": { "type": "boolean" }, "expected_count": { "type": "integer", "minimum": 0 }, "idempotency_key": { "type": "string" }, "target": { "type": "string" } }, "required": [] }, "DeleteResponse": { "oneOf": [ { "type": "object", "properties": { "dry_run": { "const": true }, "snapshot_id": { "type": "string" }, "found": { "type": "boolean" }, "would_delete": { "type": "object", "properties": { "mind_sync_rows": { "type": "number" } }, "required": [ "mind_sync_rows" ] }, "expected_count": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } }, "required": [ "dry_run", "snapshot_id", "found", "would_delete", "expected_count", "message" ] }, { "type": "object", "properties": { "success": { "const": true }, "status": { "const": "purged" }, "snapshot_id": { "type": "string" }, "deleted": { "type": "object", "properties": { "mind_sync_rows": { "type": "number" } }, "required": [ "mind_sync_rows" ] }, "summary": { "type": "string" } }, "required": [ "success", "status", "snapshot_id", "deleted", "summary" ] } ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "success": { "const": false }, "details": {}, "expected_count": { "type": "number" }, "retryAfter": { "type": "string", "format": "date-time" } }, "required": [ "error" ] } } } }