{ "openapi": "3.1.0", "info": { "title": "Optiverse API", "version": "2.0.0", "description": "The Optiverse public API. Every v2 operation is also an MCP tool at https://assistant.optiverse.ai/mcp (see `x-mcp-tool`).\n\nAuthenticate with your personal API key: `Authorization: Bearer optiuser_v1_…` (Settings → API).\n\nSuccess responses are `{ data, pagination? }`; errors are `{ error: { code, message, retryable, requestId } }`.\n\nEvery response carries `X-Request-Id`; authenticated responses also carry `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers." }, "servers": [ { "url": "https://developer.optiverse.ai/api" } ], "tags": [ { "name": "Agent" }, { "name": "Meetings" }, { "name": "Calendar" }, { "name": "Topics" }, { "name": "Summaries" }, { "name": "Boards" }, { "name": "Help" }, { "name": "Uploads" }, { "name": "Meta" } ], "paths": { "/v2/agent/ask": { "post": { "operationId": "askOptiverse", "summary": "Ask Optiverse", "description": "Ask the full Optiverse Agent to answer from your private Optiverse data or act through your connected integrations. It may make difficult-to-reverse changes in external systems.", "tags": [ "Agent" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 32000, "description": "The request for the Optiverse Agent. Markdown is supported." }, "sessionId": { "type": "string", "format": "uuid", "description": "Session to continue, from a previous answer. Omit to start a new private session." } }, "required": [ "message" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "answer": { "type": "string", "description": "The final answer in Markdown." }, "sessionId": { "type": "string", "format": "uuid", "description": "Pass back as sessionId to continue the same session." } }, "required": [ "answer", "sessionId" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "text/event-stream": { "schema": { "type": "string" }, "description": "Sent when the request has `Accept: text/event-stream`: `progress` events (`{ message }`; Ask Optiverse first sends one `session` event, `{ sessionId }`), then one `result` event (the JSON body) or one `error` event (the error envelope)." } } }, "400": { "description": "The request is invalid (`invalid_request`), or the turn was cancelled through the cancel endpoint (`cancelled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "No credits left for Ask Optiverse (`insufficient_credits`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The agent failed (`internal_error`). After execution starts, actions may already have happened: retryable is false and details.sessionId identifies the session to inspect.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The connection to the agent was interrupted (`upstream_unavailable`). Ambiguous failures have retryable: false and details.sessionId; inspect the session before resubmitting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The answer took too long (`timeout`). The agent may still be running: retryable is false and details.sessionId identifies the session to inspect or cancel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "10 requests per 60s (agent)", "x-mcp-tool": "ask_optiverse" } }, "/v2/agent/sessions": { "get": { "operationId": "listAgentSessions", "summary": "List Ask Optiverse sessions", "description": "Ask Optiverse sessions started over the API or MCP, newest first.", "tags": [ "Agent" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "api", "mcp" ], "description": "Where the session started; either transport can continue it." }, "createdAt": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "sessionId", "title", "source", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "sessions" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)" } }, "/v2/agent/sessions/{sessionId}/messages": { "get": { "operationId": "getAgentSessionMessages", "summary": "Get Ask Optiverse session messages", "description": "The messages and answers of one Ask Optiverse session, oldest first.", "tags": [ "Agent" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Session ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "session": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "api", "mcp" ], "description": "Where the session started; either transport can continue it." }, "createdAt": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "sessionId", "title", "source", "createdAt", "updatedAt" ], "additionalProperties": false }, "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string" }, "message": { "type": [ "string", "null" ], "description": "What was asked." }, "answer": { "type": [ "string", "null" ], "description": "The answer, or null while the turn is running." }, "completed": { "type": "boolean" } }, "required": [ "messageId", "createdAt", "message", "answer", "completed" ], "additionalProperties": false } } }, "required": [ "session", "messages" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)" } }, "/v2/agent/sessions/{sessionId}/cancel": { "post": { "operationId": "cancelAgentSession", "summary": "Cancel an Ask Optiverse turn", "description": "Stops the turn a session is running. cancelled is false when nothing was running.", "tags": [ "Agent" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Session ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "cancelled": { "type": "boolean" } }, "required": [ "sessionId", "cancelled" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)" } }, "/v2/meetings/search": { "get": { "operationId": "searchMeetings", "summary": "Search meetings", "description": "Full-text search across every meeting transcript the user can access. Returns matching quotes with speaker, meeting title and date. Use get_meeting or get_meeting_analysis to go deeper on a result. Pass dateFrom/dateTo whenever the question is about a time period.", "tags": [ "Meetings" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keywords, e.g. \"budget review Q3\".", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of matching quotes (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Inclusive lower bound on when the meeting happened (ISO date or timestamp).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Upper bound on when the meeting happened. A date includes that whole UTC day; a timestamp is exclusive.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "matches": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "meetingTitle": { "type": "string" }, "meetingDate": { "type": [ "string", "null" ] }, "speaker": { "type": "string" }, "quote": { "type": "string" }, "sentenceId": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Position of the quote in the transcript." } }, "required": [ "recordId", "meetingTitle", "meetingDate", "speaker", "quote", "sentenceId" ], "additionalProperties": false } }, "meetingCount": { "type": "integer", "description": "Distinct meetings among the matches." } }, "required": [ "matches", "meetingCount" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "search_meetings" } }, "/v2/meetings": { "get": { "operationId": "listMeetings", "summary": "List meetings", "description": "List recorded meetings the user can access, most recent first, with a one-sentence summary each. Filter by meeting date, title keyword, attendee email or attendee domain. To pick up new meetings since a point in time, filter on createdFrom: when a meeting became available to the user. Paginate with offset.", "tags": [ "Meetings" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Inclusive lower bound on when the meeting happened (ISO date or timestamp).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Upper bound on when the meeting happened. A date includes that whole UTC day; a timestamp is exclusive.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "createdFrom", "in": "query", "required": false, "description": "Inclusive lower bound on when the meeting became available to the user: recorded, uploaded or shared (ISO date or timestamp).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "createdTo", "in": "query", "required": false, "description": "Upper bound on when the meeting became available to the user. A date includes that whole UTC day; a timestamp is exclusive.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "titleSearch", "in": "query", "required": false, "description": "Case-insensitive keyword in the meeting title.", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "attendeeEmail", "in": "query", "required": false, "description": "Only meetings with this attendee email (partial match).", "schema": { "type": "string", "minLength": 1, "maxLength": 320 } }, { "name": "attendeeDomain", "in": "query", "required": false, "description": "Only meetings with at least one attendee from this email domain, e.g. \"acme.com\".", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "meetings": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "description": "Meeting date (YYYY-MM-DD)." }, "startDate": { "type": [ "string", "null" ], "description": "Meeting start (ISO timestamp)." }, "endDate": { "type": [ "string", "null" ], "description": "Meeting end (ISO timestamp)." }, "durationMinutes": { "type": [ "number", "null" ] }, "attendees": { "type": "array", "items": { "type": "string" } }, "organizer": { "type": [ "string", "null" ], "description": "Calendar organizer email." }, "role": { "type": [ "string", "null" ], "description": "Your access to the meeting: owner, invited or guest." }, "createdAt": { "type": [ "string", "null" ], "description": "When the meeting became available to you: recorded, uploaded or shared (ISO timestamp)." }, "summary": { "type": [ "string", "null" ] } }, "required": [ "recordId", "title", "date", "startDate", "endDate", "durationMinutes", "attendees", "organizer", "role", "createdAt", "summary" ], "additionalProperties": false } } }, "required": [ "meetings" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "list_meetings" } }, "/v2/meetings/analysis": { "get": { "operationId": "getMeetingAnalysis", "summary": "Get meeting analysis", "description": "Analysis for up to 20 meetings: one-sentence summary, topics with takeaways, and action items. With includeSummaries=true, also the meeting notes and protocol Q&A sections. Meetings that do not exist or that the user cannot access are left out.", "tags": [ "Meetings" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "recordIds", "in": "query", "required": true, "description": "Meeting record IDs (1-20).", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 20 }, "style": "form", "explode": true }, { "name": "includeSummaries", "in": "query", "required": false, "description": "Also return notes and protocol Q&A sections.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "meetings": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "oneSentenceSummary": { "type": [ "string", "null" ] }, "topics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "takeaways": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string" }, "sentenceIds": { "type": "array", "items": { "type": "integer" }, "description": "Transcript sentence ids that support this item." } }, "required": [ "content", "sentenceIds" ], "additionalProperties": false } } }, "required": [ "name", "description", "takeaways" ], "additionalProperties": false } }, "actionItems": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "isDone": { "type": "boolean" }, "sentenceIds": { "type": "array", "items": { "type": "integer" }, "description": "Transcript sentence ids that support this item." } }, "required": [ "text", "type", "isDone", "sentenceIds" ], "additionalProperties": false } }, "summaries": { "type": "array", "items": { "type": "object", "properties": { "protocolId": { "type": [ "string", "null" ] }, "protocolTitle": { "type": "string" }, "markdown": { "type": [ "string", "null" ] }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "answers": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "answers" ], "additionalProperties": false } } }, "required": [ "protocolId", "protocolTitle", "markdown", "sections" ], "additionalProperties": false } } }, "required": [ "recordId", "title", "oneSentenceSummary", "topics", "actionItems" ], "additionalProperties": false } } }, "required": [ "meetings" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "get_meeting_analysis" } }, "/v2/meetings/{recordId}": { "get": { "operationId": "getMeeting", "summary": "Get meeting", "description": "Load one meeting: title, date, duration, attendees, speakers and the full transcript. Transcript lines are grouped by speaker as \"[Speaker]:\" blocks. Over MCP, «n» after a sentence is its sentence id (as in search_meetings and get_meeting_analysis); REST returns plain sentences.", "tags": [ "Meetings" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "recordId", "in": "path", "required": true, "description": "Meeting record ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ], "description": "Meeting start (ISO timestamp)." }, "durationMinutes": { "type": [ "number", "null" ] }, "attendees": { "type": "array", "items": { "type": "string" } }, "speakers": { "type": "array", "items": { "type": "string" } }, "transcript": { "type": "string" } }, "required": [ "recordId", "title", "date", "durationMinutes", "attendees", "speakers", "transcript" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "get_meeting" } }, "/v2/contacts/meetings": { "get": { "operationId": "findContactMeetings", "summary": "Find meetings with a person", "description": "Fuzzy-match a person's name or email across calendar attendees, meeting titles and transcript speaker labels, and return the meetings they appear in. Handles partial names and typos.", "tags": [ "Meetings" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Name or email, e.g. \"Mario Assaf\" or \"mario@acme.com\".", "schema": { "type": "string", "minLength": 1, "maxLength": 320 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 15 } }, { "name": "threshold", "in": "query", "required": false, "description": "Similarity threshold 0-1; lower is fuzzier.", "schema": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Inclusive lower bound on when the meeting happened (ISO date or timestamp).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Upper bound on when the meeting happened. A date includes that whole UTC day; a timestamp is exclusive.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "meetings": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "date": { "type": [ "string", "null" ] }, "durationMinutes": { "type": [ "number", "null" ] }, "summary": { "type": [ "string", "null" ] }, "matchScore": { "type": "number" }, "matchedValue": { "type": "string" }, "matchSource": { "type": "string", "enum": [ "attendee", "title", "speaker" ] }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "email", "name" ], "additionalProperties": false } } }, "required": [ "recordId", "title", "date", "durationMinutes", "summary", "matchScore", "matchedValue", "matchSource", "attendees" ], "additionalProperties": false } }, "total": { "type": "integer" } }, "required": [ "meetings", "total" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "find_contact_meetings" } }, "/v2/calendar/events": { "get": { "operationId": "listUpcomingEvents", "summary": "List upcoming calendar events", "description": "Upcoming events from the user's synced Google or Outlook calendar, soonest first, with attendees and join URL. Only events that have not ended; for past recorded meetings use list_meetings.", "tags": [ "Calendar" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Only events starting at or after this time. Defaults to now.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Only events starting at or before this time.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "titleSearch", "in": "query", "required": false, "description": "Case-insensitive keyword in the event title.", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "attendeeEmail", "in": "query", "required": false, "description": "Only events with this attendee email (partial match).", "schema": { "type": "string", "minLength": 1, "maxLength": 320 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "eventStart": { "type": [ "string", "null" ] }, "eventEnd": { "type": [ "string", "null" ] }, "attendees": { "type": "array", "items": { "type": "string" } }, "organizer": { "type": [ "string", "null" ] }, "joinUrl": { "type": [ "string", "null" ] }, "meetingProvider": { "type": [ "string", "null" ] }, "joinPref": { "type": [ "boolean", "null" ], "description": "Whether the Optiverse notetaker is set to join." } }, "required": [ "eventId", "title", "eventStart", "eventEnd", "attendees", "organizer", "joinUrl", "meetingProvider", "joinPref" ], "additionalProperties": false } } }, "required": [ "events" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "list_upcoming_events" } }, "/v2/topics": { "get": { "operationId": "browseTopics", "summary": "Browse meeting topics", "description": "Topics discussed in the user's meetings, grouped by meeting, most recent first. Use it to find the meetings about a theme: scan the topics yourself for relevance. Always pass dateFrom/dateTo for a time period. If hasMore is true the topic cap was reached; narrow the date range or raise maxTopics. For a whole-period overview use analyze_topic_trends instead.", "tags": [ "Topics" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "dateFrom", "in": "query", "required": false, "description": "Inclusive lower bound on when the meeting happened (ISO date or timestamp).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Upper bound on when the meeting happened. A date includes that whole UTC day; a timestamp is exclusive.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "maxTopics", "in": "query", "required": false, "description": "Maximum topic rows to read (1-1000).", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 300 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "meetings": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "meetingTitle": { "type": [ "string", "null" ] }, "meetingDate": { "type": [ "string", "null" ] }, "topics": { "type": "array", "items": { "type": "string" }, "description": "\"Topic: description\" labels." } }, "required": [ "recordId", "meetingTitle", "meetingDate", "topics" ], "additionalProperties": false } }, "topicCount": { "type": "integer" }, "totalTopicCount": { "type": "integer", "description": "Topics in the date scope, including those past the cap." }, "hasMore": { "type": "boolean" }, "warning": { "type": "string", "description": "Present when the result is partial; explains how to narrow the request." } }, "required": [ "meetings", "topicCount", "totalTopicCount", "hasMore" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "browse_topics" } }, "/v2/topics/trends": { "get": { "operationId": "analyzeTopicTrends", "summary": "Analyze topic trends", "description": "How topics evolve over time: meetings grouped by week or month (newest first), with the most frequent topics, the meetings and key takeaways in each period. Pass a topic keyword to follow one theme, or omit it for overall trends.", "tags": [ "Topics" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "topic", "in": "query", "required": false, "description": "Topic name or keyword to follow. Omit for overall trends.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Inclusive lower bound on when the meeting happened (ISO date or timestamp).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Upper bound on when the meeting happened. A date includes that whole UTC day; a timestamp is exclusive.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "timezone", "in": "query", "required": false, "description": "IANA timezone used to group meetings into local weeks or months, e.g. \"Europe/Zurich\". Defaults to UTC.", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "week", "month" ], "default": "week" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum topics to analyze (5-100).", "schema": { "type": "integer", "minimum": 5, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "periods": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "description": "Week (\"2026-W41\") or month (\"2026-10\") label." }, "meetingCount": { "type": "integer" }, "topics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "name", "count" ], "additionalProperties": false } }, "meetings": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] } }, "required": [ "recordId", "title" ], "additionalProperties": false } }, "takeaways": { "type": "array", "items": { "type": "string" } } }, "required": [ "period", "meetingCount", "topics", "meetings", "takeaways" ], "additionalProperties": false } }, "topRecurring": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "name", "count" ], "additionalProperties": false } }, "meetingCount": { "type": "integer" }, "topicCount": { "type": "integer" }, "hasMore": { "type": "boolean" }, "timezone": { "type": "string" }, "warning": { "type": "string", "description": "Present when the result is partial; explains how to narrow the request." } }, "required": [ "periods", "topRecurring", "meetingCount", "topicCount", "hasMore", "timezone" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "analyze_topic_trends" } }, "/v2/summary-templates": { "get": { "operationId": "listSummaryTemplates", "summary": "List summary templates", "description": "Summary templates (protocols) the user can use, newest first. Pass a protocolId to get_meeting_summaries to read the summaries a template produced.", "tags": [ "Summaries" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "protocolId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "summaryType": { "type": "string", "enum": [ "structured", "unstructured", "docx" ], "description": "structured: Q&A sections; unstructured: markdown; docx: a signed download URL." }, "managedBy": { "type": "string", "enum": [ "optiverse", "user" ] }, "createdAt": { "type": "string" } }, "required": [ "protocolId", "title", "description", "summaryType", "managedBy", "createdAt" ], "additionalProperties": false } } }, "required": [ "templates" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "list_summary_templates" } }, "/v2/summaries": { "get": { "operationId": "getMeetingSummaries", "summary": "Get meeting summaries", "description": "Summaries produced by one summary template, newest first, including historical formats after the template changes. Each summary has its own summaryType: Q&A sections, markdown, or a signed .docx download URL valid for one hour (null when no document is available). The page summaryType is mixed when it contains several formats. Filter by meeting or by summary creation date.", "tags": [ "Summaries" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "protocolId", "in": "query", "required": true, "description": "Summary template ID from list_summary_templates.", "schema": { "type": "string", "format": "uuid" } }, { "name": "recordId", "in": "query", "required": false, "description": "Only summaries of this meeting.", "schema": { "type": "string", "format": "uuid" } }, { "name": "dateFrom", "in": "query", "required": false, "description": "Only summaries created at or after this time.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dateTo", "in": "query", "required": false, "description": "Only summaries created at or before this time.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results (1-50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of results to skip.", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "protocolId": { "type": "string", "format": "uuid" }, "summaryType": { "type": "string", "enum": [ "structured", "unstructured", "docx", "mixed" ], "description": "Format on this page, or mixed for several formats. An empty page uses the template's current format." }, "summaries": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "summaryType": { "type": "string", "const": "structured" }, "recordId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "question": { "type": "string" }, "answerType": { "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "answer": { "type": "string" }, "referenceIds": { "type": "array", "items": { "type": [ "number", "string" ] }, "description": "Transcript sentence ids that support the answer." } }, "required": [ "answer", "referenceIds" ], "additionalProperties": false } } }, "required": [ "title", "question", "answerType", "answers" ], "additionalProperties": false } } }, "required": [ "summaryType", "recordId", "createdAt", "sections" ], "additionalProperties": false }, { "type": "object", "properties": { "summaryType": { "type": "string", "const": "unstructured" }, "recordId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string" }, "markdown": { "type": [ "string", "null" ] } }, "required": [ "summaryType", "recordId", "createdAt", "markdown" ], "additionalProperties": false }, { "type": "object", "properties": { "summaryType": { "type": "string", "const": "docx" }, "recordId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string" }, "downloadUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Signed download URL, or null when no document is available (not generated yet, or the file is gone)." }, "expiresIn": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Seconds until downloadUrl expires, or null when no document is available." } }, "required": [ "summaryType", "recordId", "createdAt", "downloadUrl", "expiresIn" ], "additionalProperties": false } ] } } }, "required": [ "protocolId", "summaryType", "summaries" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "get_meeting_summaries" } }, "/v2/boards": { "get": { "operationId": "listBoards", "summary": "List boards", "description": "The user's Optiverse task boards with their columns, open-task counts and board IDs. Call it first to find the boardId the other board tools need.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "boards": { "type": "array", "items": { "type": "object", "properties": { "boardId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "boardType": { "type": "string", "enum": [ "personal", "project" ] }, "color": { "type": [ "string", "null" ] }, "openTaskCount": { "type": "integer" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "sectionId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "number" }, "color": { "type": [ "string", "null" ] }, "isInbox": { "type": "boolean" }, "isDone": { "type": "boolean" }, "isArchive": { "type": "boolean" }, "taskCount": { "type": "integer" } }, "required": [ "sectionId", "name", "order", "color", "isInbox", "isDone", "isArchive" ], "additionalProperties": false } } }, "required": [ "boardId", "title", "boardType", "color", "openTaskCount", "sections" ], "additionalProperties": false } } }, "required": [ "boards" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "list_boards" }, "post": { "operationId": "createBoard", "summary": "Create board", "description": "Create a project board with the default Inbox, To Do, In Progress and Done columns.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Board title." }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex color, e.g. #3B82F6." }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Board description." } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "board": { "type": "object", "properties": { "boardId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "boardType": { "type": "string", "enum": [ "personal", "project" ] }, "color": { "type": [ "string", "null" ] } }, "required": [ "boardId", "title", "description", "boardType", "color" ], "additionalProperties": false }, "sections": { "type": "array", "items": { "type": "object", "properties": { "sectionId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "number" }, "color": { "type": [ "string", "null" ] }, "isInbox": { "type": "boolean" }, "isDone": { "type": "boolean" }, "isArchive": { "type": "boolean" }, "taskCount": { "type": "integer" } }, "required": [ "sectionId", "name", "order", "color", "isInbox", "isDone", "isArchive" ], "additionalProperties": false } } }, "required": [ "board", "sections" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "create_board" } }, "/v2/boards/{boardId}": { "get": { "operationId": "getBoard", "summary": "Get board", "description": "One board with its columns (sections), labels and tasks. Completed tasks are left out unless includeCompleted is true.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } }, { "name": "includeCompleted", "in": "query", "required": false, "description": "Include completed tasks and tasks in the Done column.", "schema": { "type": "boolean", "default": false } }, { "name": "taskLimit", "in": "query", "required": false, "description": "Maximum tasks to return (1-200).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 80 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "board": { "type": "object", "properties": { "boardId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "boardType": { "type": "string", "enum": [ "personal", "project" ] }, "color": { "type": [ "string", "null" ] } }, "required": [ "boardId", "title", "boardType", "color" ], "additionalProperties": false }, "sections": { "type": "array", "items": { "type": "object", "properties": { "sectionId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "number" }, "color": { "type": [ "string", "null" ] }, "isInbox": { "type": "boolean" }, "isDone": { "type": "boolean" }, "isArchive": { "type": "boolean" }, "taskCount": { "type": "integer" } }, "required": [ "sectionId", "name", "order", "color", "isInbox", "isDone", "isArchive" ], "additionalProperties": false } }, "labels": { "type": "array", "items": { "type": "object", "properties": { "labelId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "order": { "type": "number" } }, "required": [ "labelId", "name", "color", "order" ], "additionalProperties": false } }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "sectionId": { "type": "string", "format": "uuid" }, "priority": { "type": "integer" }, "dueDate": { "type": [ "string", "null" ] }, "labelIds": { "type": "array", "items": { "type": "string" } }, "completedAt": { "type": [ "string", "null" ] }, "subtaskCount": { "type": "integer" } }, "required": [ "taskId", "title", "sectionId", "priority", "dueDate", "labelIds", "completedAt", "subtaskCount" ], "additionalProperties": false } } }, "required": [ "board", "sections", "labels", "tasks" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "get_board" }, "patch": { "operationId": "updateBoard", "summary": "Update board", "description": "Rename a board, or change its color or description. Only the board owner can change these.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "New title." }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "New hex color." }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "New description." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "board": { "type": "object", "properties": { "boardId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "boardType": { "type": "string", "enum": [ "personal", "project" ] }, "color": { "type": [ "string", "null" ] } }, "required": [ "boardId", "title", "description", "boardType", "color" ], "additionalProperties": false } }, "required": [ "board" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "update_board" } }, "/v2/tasks/search": { "get": { "operationId": "searchTasks", "summary": "Search tasks", "description": "Search tasks across all boards, or one board with boardId. Filter by text in the title or description, priority, column name, label names and due date.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Text to find in task titles and descriptions.", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "boardId", "in": "query", "required": false, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } }, { "name": "priority", "in": "query", "required": false, "description": "Only these priorities (1 = urgent … 4 = low).", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 4, "description": "1 = urgent, 2 = high, 3 = medium, 4 = low." }, "maxItems": 4 }, "style": "form", "explode": true }, { "name": "sectionName", "in": "query", "required": false, "description": "Only tasks in a column with this name, e.g. \"In Progress\".", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "labelNames", "in": "query", "required": false, "description": "Only tasks with these labels.", "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 20 }, "style": "form", "explode": true }, { "name": "dueBefore", "in": "query", "required": false, "description": "Inclusive upper due-date bound. A date includes the whole UTC day; timestamps use their timezone. Date-only tasks match any overlap.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "dueAfter", "in": "query", "required": false, "description": "Inclusive lower due-date bound. A date includes the whole UTC day; timestamps use their timezone. Date-only tasks match any overlap.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2}))?$" } }, { "name": "includeCompleted", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum tasks to return (1-100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "boardId": { "type": "string", "format": "uuid" }, "boardTitle": { "type": "string" }, "sectionName": { "type": [ "string", "null" ] }, "priority": { "type": "integer" }, "dueDate": { "type": [ "string", "null" ] } }, "required": [ "taskId", "title", "boardId", "boardTitle", "sectionName", "priority", "dueDate" ], "additionalProperties": false } } }, "required": [ "tasks" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "search_tasks" } }, "/v2/boards/{boardId}/sections": { "post": { "operationId": "manageBoardSection", "summary": "Manage board columns", "description": "Create, update, delete or reorder the columns (sections) of a board. update and delete take sectionId or the current sectionName. Deleting a column moves its tasks to Inbox; Inbox and Done can't be deleted. reorder takes the full list in orders.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "update", "delete", "reorder" ] }, "sectionId": { "type": "string", "format": "uuid", "description": "Column to update or delete." }, "sectionName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Current name of the column to update or delete, when sectionId is unknown." }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "New column name (create, update)." }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Column hex color (create, update)." }, "order": { "type": "number", "description": "Position index (create, update)." }, "orders": { "type": "array", "items": { "type": "object", "properties": { "sectionId": { "type": "string", "format": "uuid" }, "order": { "type": "number" } }, "required": [ "sectionId", "order" ], "additionalProperties": false }, "minItems": 1, "maxItems": 50, "description": "Every column with its new position (reorder)." } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "update", "delete", "reorder" ] }, "section": { "type": "object", "properties": { "sectionId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "number" }, "color": { "type": [ "string", "null" ] }, "isInbox": { "type": "boolean" }, "isDone": { "type": "boolean" }, "isArchive": { "type": "boolean" }, "taskCount": { "type": "integer" } }, "required": [ "sectionId", "name", "order", "color", "isInbox", "isDone", "isArchive" ], "additionalProperties": false }, "sections": { "type": "array", "items": { "type": "object", "properties": { "sectionId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "order": { "type": "number" }, "color": { "type": [ "string", "null" ] }, "isInbox": { "type": "boolean" }, "isDone": { "type": "boolean" }, "isArchive": { "type": "boolean" }, "taskCount": { "type": "integer" } }, "required": [ "sectionId", "name", "order", "color", "isInbox", "isDone", "isArchive" ], "additionalProperties": false } }, "deletedSectionId": { "type": "string", "format": "uuid" } }, "required": [ "action" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "manage_board_section" } }, "/v2/boards/{boardId}/labels": { "post": { "operationId": "manageBoardLabel", "summary": "Manage board labels", "description": "Create, update or delete a label on a board. update and delete take labelId or the current labelName.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "update", "delete" ] }, "labelId": { "type": "string", "format": "uuid", "description": "Label to update or delete." }, "labelName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Current name of the label to update or delete, when labelId is unknown." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "New label name (create, update)." }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Label hex color (create, update)." } }, "required": [ "action" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "create", "update", "delete" ] }, "label": { "type": "object", "properties": { "labelId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "order": { "type": "number" } }, "required": [ "labelId", "name", "color", "order" ], "additionalProperties": false }, "deletedLabelId": { "type": "string", "format": "uuid" } }, "required": [ "action" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "manage_board_label" } }, "/v2/boards/{boardId}/tasks": { "post": { "operationId": "createTask", "summary": "Create task", "description": "Create one task on a board. Prefer sectionName over guessing IDs. Set transcriptId when the task comes from a meeting action item. For three or more tasks use batch_create_tasks.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Task title." }, "description": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Task description (plain text or markdown)." }, "sectionId": { "type": "string", "format": "uuid", "description": "Column to put the task in. Defaults to Inbox." }, "sectionName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Column name, e.g. \"To Do\", when sectionId is unknown." }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "description": "1 = urgent, 2 = high, 3 = medium, 4 = low." }, "labelNames": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 20, "description": "Label names on this board." }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2})?$", "description": "Due date, YYYY-MM-DD or YYYY-MM-DDThh:mm." }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "completed": { "type": "boolean" } }, "required": [ "title" ], "additionalProperties": false }, "maxItems": 50 }, "transcriptId": { "type": "string", "format": "uuid", "description": "Meeting record ID when the task comes from a meeting (sets source to transcript)." }, "position": { "anyOf": [ { "type": "string", "enum": [ "top", "bottom" ] }, { "type": "object", "properties": { "after": { "type": "string", "format": "uuid" } }, "required": [ "after" ], "additionalProperties": false } ], "description": "Place the task at the \"top\" or \"bottom\" of its column, or { \"after\": taskId }." } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "task": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid" }, "boardId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "title": { "type": "string" }, "description": { "type": "string" }, "sectionId": { "type": "string", "format": "uuid", "description": "Column the task is in." }, "priority": { "type": "integer" }, "labelIds": { "type": "array", "items": { "type": "string" } }, "dueDate": { "type": [ "string", "null" ] }, "reminderMinutes": { "type": [ "number", "null" ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "completed": { "type": "boolean" } }, "required": [ "id", "title", "completed" ], "additionalProperties": false } }, "source": { "type": "string" }, "transcriptId": { "type": [ "string", "null" ], "description": "Meeting the task was created from." }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "taskId", "boardId", "title", "description", "sectionId", "priority", "labelIds", "dueDate", "reminderMinutes", "subtasks", "source", "transcriptId", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "create_task" } }, "/v2/boards/{boardId}/tasks/{taskId}": { "patch": { "operationId": "updateTask", "summary": "Update task", "description": "Update one task: title, description, priority, labels, due date or subtasks, and optionally move it to another column. completed=true marks it done and moves it to Done. labelNames and subtasks replace the existing lists. To move several tasks to one column use move_tasks.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } }, { "name": "taskId", "in": "path", "required": true, "description": "Task to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "New title." }, "description": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "New description." }, "sectionId": { "type": "string", "format": "uuid", "description": "Move to this column." }, "sectionName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Move to the column with this name." }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "description": "1 = urgent, 2 = high, 3 = medium, 4 = low." }, "labelNames": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 20, "description": "Replace the labels with these." }, "dueDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2})?$", "description": "Due date, YYYY-MM-DD or YYYY-MM-DDThh:mm." }, { "type": "null" } ], "description": "New due date, or null to clear it." }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Existing subtask ID; omit for a new one." }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "completed": { "type": "boolean" } }, "required": [ "title" ], "additionalProperties": false }, "maxItems": 50, "description": "Replace the subtasks with this list." }, "position": { "anyOf": [ { "type": "string", "enum": [ "top", "bottom" ] }, { "type": "object", "properties": { "after": { "type": "string", "format": "uuid" } }, "required": [ "after" ], "additionalProperties": false } ], "description": "Place the task at the \"top\" or \"bottom\" of its column, or { \"after\": taskId }." }, "completed": { "type": "boolean", "description": "true marks the task done; false reopens it." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "task": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid" }, "boardId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "title": { "type": "string" }, "description": { "type": "string" }, "sectionId": { "type": "string", "format": "uuid", "description": "Column the task is in." }, "priority": { "type": "integer" }, "labelIds": { "type": "array", "items": { "type": "string" } }, "dueDate": { "type": [ "string", "null" ] }, "reminderMinutes": { "type": [ "number", "null" ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "completed": { "type": "boolean" } }, "required": [ "id", "title", "completed" ], "additionalProperties": false } }, "source": { "type": "string" }, "transcriptId": { "type": [ "string", "null" ], "description": "Meeting the task was created from." }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "taskId", "boardId", "title", "description", "sectionId", "priority", "labelIds", "dueDate", "reminderMinutes", "subtasks", "source", "transcriptId", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "task" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "update_task" } }, "/v2/boards/{boardId}/tasks/batch": { "post": { "operationId": "batchCreateTasks", "summary": "Create several tasks", "description": "Create up to 40 tasks on one board in one call, for example a meeting's action items. All columns, labels and dates are validated before writing. Each task commits atomically; a later failure returns status=partial with confirmed tasks, the failed item and unattempted indexes. Never replay the whole batch after a partial result; reconcile uncertainTaskId before retrying that item.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Task title." }, "description": { "type": "string", "minLength": 1, "maxLength": 10000, "description": "Task description (plain text or markdown)." }, "sectionId": { "type": "string", "format": "uuid", "description": "Column to put the task in. Defaults to Inbox." }, "sectionName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Column name, e.g. \"To Do\", when sectionId is unknown." }, "priority": { "type": "integer", "minimum": 1, "maximum": 4, "description": "1 = urgent, 2 = high, 3 = medium, 4 = low." }, "labelNames": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 20, "description": "Label names on this board." }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2})?$", "description": "Due date, YYYY-MM-DD or YYYY-MM-DDThh:mm." }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "completed": { "type": "boolean" } }, "required": [ "title" ], "additionalProperties": false }, "maxItems": 50 }, "transcriptId": { "type": "string", "format": "uuid", "description": "Meeting record ID when the task comes from a meeting (sets source to transcript)." } }, "required": [ "title" ], "additionalProperties": false }, "minItems": 1, "maxItems": 40 } }, "required": [ "tasks" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid" }, "boardId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "title": { "type": "string" }, "description": { "type": "string" }, "sectionId": { "type": "string", "format": "uuid", "description": "Column the task is in." }, "priority": { "type": "integer" }, "labelIds": { "type": "array", "items": { "type": "string" } }, "dueDate": { "type": [ "string", "null" ] }, "reminderMinutes": { "type": [ "number", "null" ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "completed": { "type": "boolean" } }, "required": [ "id", "title", "completed" ], "additionalProperties": false } }, "source": { "type": "string" }, "transcriptId": { "type": [ "string", "null" ], "description": "Meeting the task was created from." }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "taskId", "boardId", "title", "description", "sectionId", "priority", "labelIds", "dueDate", "reminderMinutes", "subtasks", "source", "transcriptId", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "status": { "type": "string", "enum": [ "completed", "partial" ] }, "remainingTaskIndexes": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "description": "Zero-based indexes never attempted after the failed item; empty on completion." }, "failure": { "type": "object", "properties": { "taskIndex": { "type": "integer", "minimum": 0, "description": "Zero-based index of the failed or unconfirmed item." }, "code": { "type": "string", "enum": [ "not_found", "ambiguous", "invalid_request", "forbidden", "not_allowed", "failed" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean", "const": false, "description": "Do not replay the whole batch; already confirmed tasks would be duplicated." }, "uncertainTaskId": { "type": "string", "format": "uuid", "description": "The write response was lost. Look up this task ID before retrying this item." } }, "required": [ "taskIndex", "code", "message", "retryable" ], "additionalProperties": false } }, "required": [ "tasks", "status", "remainingTaskIndexes" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "batch_create_tasks" } }, "/v2/boards/{boardId}/tasks/move": { "post": { "operationId": "moveTasks", "summary": "Move tasks", "description": "Move up to 50 tasks on one board to the same column, by sectionId or sectionName.", "tags": [ "Boards" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "boardId", "in": "path", "required": true, "description": "Board ID from list_boards.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "description": "Tasks to move." }, "sectionId": { "type": "string", "format": "uuid", "description": "Target column." }, "sectionName": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Target column name, when sectionId is unknown." }, "position": { "anyOf": [ { "type": "string", "enum": [ "top", "bottom" ] }, { "type": "object", "properties": { "after": { "type": "string", "format": "uuid" } }, "required": [ "after" ], "additionalProperties": false } ], "description": "Place the task at the \"top\" or \"bottom\" of its column, or { \"after\": taskId }." } }, "required": [ "taskIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string", "format": "uuid" }, "boardId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "title": { "type": "string" }, "description": { "type": "string" }, "sectionId": { "type": "string", "format": "uuid", "description": "Column the task is in." }, "priority": { "type": "integer" }, "labelIds": { "type": "array", "items": { "type": "string" } }, "dueDate": { "type": [ "string", "null" ] }, "reminderMinutes": { "type": [ "number", "null" ] }, "subtasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "completed": { "type": "boolean" } }, "required": [ "id", "title", "completed" ], "additionalProperties": false } }, "source": { "type": "string" }, "transcriptId": { "type": [ "string", "null" ], "description": "Meeting the task was created from." }, "completedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "taskId", "boardId", "title", "description", "sectionId", "priority", "labelIds", "dueDate", "reminderMinutes", "subtasks", "source", "transcriptId", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "tasks" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)", "x-mcp-tool": "move_tasks" } }, "/v2/help/search": { "get": { "operationId": "searchHelpCenter", "summary": "Search the Optiverse help center", "description": "Search the Optiverse Academy documentation: how-to guides, feature explanations, integration setup and troubleshooting. Returns matching sections with links; read a full page with get_help_article.", "tags": [ "Help" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Question or keywords, e.g. \"connect HubSpot\".", "schema": { "type": "string", "minLength": 1, "maxLength": 500 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum sections to return (1-10).", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "pageTitle": { "type": "string" }, "sectionHeading": { "type": "string" }, "url": { "type": "string" }, "slug": { "type": [ "string", "null" ], "description": "Pass to get_help_article." }, "snippet": { "type": "string" } }, "required": [ "pageTitle", "sectionHeading", "url", "slug", "snippet" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "search_help_center" } }, "/v2/help/articles": { "get": { "operationId": "getHelpArticle", "summary": "Get a help center article", "description": "Full markdown of one Optiverse Academy page, by slug (for example \"desktop-app/capture\"). Long pages are truncated at about 6,000 characters.", "tags": [ "Help" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "slug", "in": "query", "required": true, "description": "Page slug from search_help_center results.", "schema": { "type": "string", "pattern": "^(\\/?docs\\/)?[a-z0-9][a-z0-9-]*(\\/[a-z0-9][a-z0-9-]*)*\\/?$", "maxLength": 200 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "content": { "type": "string" } }, "required": [ "title", "url", "content" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "read", "x-rate-limit": "120 requests per 60s (read)", "x-mcp-tool": "get_help_article" } }, "/v2/uploads": { "post": { "operationId": "createUpload", "summary": "Start a recording upload", "description": "Returns a presigned URL for uploading one audio or video recording. PUT the file bytes to uploadUrl with requiredHeaders, then call POST /v2/uploads/{uploadId}/complete to start processing. Supported extensions: mp4, webm, mov, mp3, m4a, wav, opus, ogg.", "tags": [ "Uploads" ], "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Original file name including its extension, e.g. \"standup.mp4\"." } }, "required": [ "fileName" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid" }, "uploadUrl": { "type": "string", "format": "uri" }, "method": { "type": "string", "const": "PUT" }, "requiredHeaders": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Send these headers with the PUT." } }, "required": [ "uploadId", "uploadUrl", "method", "requiredHeaders" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)" } }, "/v2/uploads/{uploadId}/complete": { "post": { "operationId": "completeUpload", "summary": "Finish a recording upload", "description": "Call after the PUT to the presigned URL succeeded. Starts transcription and analysis; the meeting appears in list_meetings once processing finishes. Optionally names the meeting and picks the summary template.", "tags": [ "Uploads" ], "security": [ { "apiKey": [] } ], "parameters": [ { "name": "uploadId", "in": "path", "required": true, "description": "Upload ID from POST /v2/uploads.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Meeting title. Defaults to \"Untitled Upload\"." }, "protocolId": { "type": "string", "format": "uuid", "description": "Summary template to apply, from list_summary_templates." } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "uploadId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "processing" } }, "required": [ "uploadId", "status" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "The request is invalid (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key (`unauthorized`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You can read the resource but not change it (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The resource does not exist or is not accessible (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A name matches more than one item, or the session is busy (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is larger than 1 MB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (`rate_limited`); see `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected failure (`internal_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "A dependent service is temporarily unavailable (`upstream_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-access": "write", "x-rate-limit": "60 requests per 60s (write)" } }, "/v2/openapi.json": { "get": { "operationId": "getOpenApiDocument", "summary": "OpenAPI document", "description": "This document. No authentication required.", "tags": [ "Meta" ], "security": [], "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "optiuser_v1_<56 hex characters>", "description": "Personal API key from Settings → API." } }, "schemas": { "Pagination": { "type": "object", "required": [ "limit", "offset", "hasMore", "nextOffset" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": [ "integer", "null" ] }, "total": { "type": "integer" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "retryable", "requestId" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "not_found", "conflict", "payload_too_large", "insufficient_credits", "rate_limited", "cancelled", "internal_error", "not_implemented", "upstream_unavailable", "timeout" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string" }, "details": { "type": "object" } } } } } } } }