{"openapi":"3.1.0","info":{"title":"Twelfth MCP API","version":"1.0.0","description":"Public Streamable HTTP transport for the read-only Twelfth Model Context Protocol server. Workspace owners and admins create labelled bearer keys in Twelfth under Settings → AI & agents.\n\n**Errors.** Every 4xx/5xx response is `application/problem+json` (RFC 9457) with a machine-readable `code`, a human-readable `title`/`detail`, and a `hint` for recovery. JSON-RPC-level errors are additionally returned inside the 200 envelope per the JSON-RPC 2.0 spec.\n\n**Versioning.** The endpoint is offered unversioned at `/mcp` and at the version-pinned alias `/v1/mcp`; both are identical today. Callers negotiate the MCP protocol version with the `MCP-Protocol-Version` request header, and each response echoes the negotiated version in `X-Twelfth-Api-Version`. See `x-api-lifecycle` for the deprecation policy.\n\n**Rate limits.** Responses carry the IETF `RateLimit-*` headers so agents can self-throttle; a `429` includes `Retry-After`.","contact":{"name":"Twelfth AI developer enquiries","email":"hello@twelfth.ai","url":"https://twelfth.ai/developers"}},"x-api-lifecycle":{"versioning":"URL path versioning (`/v1/mcp`) plus MCP protocol-version negotiation via the `MCP-Protocol-Version` request header. A breaking change ships under a new path segment (`/v2/mcp`); the previous version keeps working during the deprecation window.","deprecationPolicy":"A deprecated endpoint or version returns a `Deprecation` header (RFC 8594) and, once a removal date is set, a `Sunset` header with that date. Breaking changes are announced at https://twelfth.ai/developers with at least 90 days' notice before the Sunset date.","supportedMcpProtocolVersions":["2025-03-26"]},"externalDocs":{"description":"Twelfth MCP server guide","url":"https://twelfth.ai/developers/mcp"},"servers":[{"url":"https://api.twelfth.ai","description":"Twelfth production API"}],"paths":{"/mcp":{"post":{"operationId":"twelfthMcpRequest","summary":"Send a JSON-RPC request to the Twelfth MCP server","description":"Initialise the stateless MCP connection, list available read-only tools or call an authorised tool. The server negotiates MCP protocol version 2025-03-26 and returns JSON-RPC responses as application/json.","security":[{"bearerAuth":[]}],"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"The MCP protocol version the client supports. Defaults to the latest supported version (2025-03-26) when omitted.","schema":{"type":"string","example":"2025-03-26"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC result or error response.","headers":{"RateLimit-Limit":{"description":"Request quota for the current window.","schema":{"type":"integer","example":120}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":119}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":47}},"RateLimit-Policy":{"description":"The advertised quota policy, as `<limit>;w=<window-seconds>`.","schema":{"type":"string","example":"120;w=60"}},"X-Twelfth-Api-Version":{"description":"The MCP protocol version this response was produced under.","schema":{"type":"string","example":"2025-03-26"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"202":{"description":"The notifications/initialized notification was accepted.","headers":{"RateLimit-Limit":{"description":"Request quota for the current window.","schema":{"type":"integer","example":120}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":119}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":47}},"RateLimit-Policy":{"description":"The advertised quota policy, as `<limit>;w=<window-seconds>`.","schema":{"type":"string","example":"120;w=60"}},"X-Twelfth-Api-Version":{"description":"The MCP protocol version this response was produced under.","schema":{"type":"string","example":"2025-03-26"}}}},"400":{"description":"Invalid MCP or JSON-RPC request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, invalid or revoked workspace bearer key.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"The MCP endpoint only accepts POST requests.","headers":{"Allow":{"description":"Permitted methods.","schema":{"type":"string","example":"POST"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limit exceeded. Retry after the window resets.","headers":{"RateLimit-Limit":{"description":"Request quota for the current window.","schema":{"type":"integer","example":120}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":119}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":47}},"RateLimit-Policy":{"description":"The advertised quota policy, as `<limit>;w=<window-seconds>`.","schema":{"type":"string","example":"120;w=60"}},"X-Twelfth-Api-Version":{"description":"The MCP protocol version this response was produced under.","schema":{"type":"string","example":"2025-03-26"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":47}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Unexpected server error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/mcp":{"$ref":"#/paths/~1mcp"}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Workspace-scoped key generated in Twelfth under Settings → AI & agents."}},"schemas":{"Problem":{"type":"object","description":"A structured, machine-readable error (RFC 9457 problem detail).","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri","description":"A URI reference identifying the problem type.","default":"about:blank"},"title":{"type":"string","description":"Short, human-readable summary of the problem type."},"status":{"type":"integer","description":"The HTTP status code.","example":401},"code":{"type":"string","description":"Stable, machine-readable error code for programmatic handling.","example":"unauthorized"},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence."},"hint":{"type":"string","description":"How to resolve or work around the error."},"instance":{"type":"string","format":"uri-reference","description":"A URI reference identifying this specific occurrence."}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}},"additionalProperties":false},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"result":true,"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":true}}}}}}}