{"openapi":"3.1.0","info":{"title":"torqee Connect API","description":"Read-only public API for torqee workspace data (sessions, transcripts, AI boards) with a realtime event stream. Authenticate with an OAuth 2.1 access token or a `torqee_` API key.","version":"1.0.0"},"servers":[{"url":"https://connect.torqee.app"}],"tags":[{"name":"Sessions","description":"Session lifecycle data"},{"name":"Transcripts","description":"Transcript segments and search"},{"name":"Boards","description":"AI-generated board contents"},{"name":"Events","description":"Realtime workspace events (SSE)"}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization code flow with PKCE. Audience must be the connect URL.","flows":{"authorizationCode":{"authorizationUrl":"https://auth.torqee.app/api/auth/oauth2/authorize","tokenUrl":"https://auth.torqee.app/api/auth/oauth2/token","scopes":{"torqee:sessions:read":"Read sessions in the workspace","torqee:transcripts:read":"Read and search transcripts","torqee:boards:read":"Read AI board contents"}}}},"apiKey":{"type":"http","scheme":"bearer","description":"Workspace API key issued from the torqee web app. Pass the `torqee_`-prefixed key as the bearer token. API keys carry the same read scopes as OAuth tokens."}},"schemas":{"WorkspaceEvent":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"session.created"},"sessionId":{"type":"string"},"occurredAt":{"type":"string"},"data":{"type":"object","properties":{"sessionId":{"type":"string"},"occurredAt":{"type":"string"},"session":{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","label","memo","status","startedAt","endedAt","createdAt","updatedAt"],"additionalProperties":false}},"required":["sessionId","occurredAt","session"],"additionalProperties":false}},"required":["type","sessionId","occurredAt","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"session.status_changed"},"sessionId":{"type":"string"},"occurredAt":{"type":"string"},"data":{"type":"object","properties":{"sessionId":{"type":"string"},"status":{"type":"string"},"previousStatus":{"type":"string"},"occurredAt":{"type":"string"},"session":{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","label","memo","status","startedAt","endedAt","createdAt","updatedAt"],"additionalProperties":false}},"required":["sessionId","status","previousStatus","occurredAt","session"],"additionalProperties":false}},"required":["type","sessionId","occurredAt","data"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"transcript.segment.created"},"sessionId":{"type":"string"},"occurredAt":{"type":"string"},"data":{"type":"object","properties":{"sessionId":{"type":"string"},"occurredAt":{"type":"string"},"id":{"type":"string"},"sequence":{"type":"number"},"timestampStart":{"type":"number"},"timestampEnd":{"type":"number"},"speakerLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"type":"string"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["sessionId","occurredAt","id","sequence","timestampStart","timestampEnd","speakerLabel","text","confidence","createdAt"],"additionalProperties":false}},"required":["type","sessionId","occurredAt","data"],"additionalProperties":false}]},"EventStreamFilters":{"$schema":"https://json-schema.org/draft/2020-12/schema","minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["session.created","session.status_changed","transcript.segment.created"]},"sessionId":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":false}}}},"paths":{"/api/v1/events/stream":{"get":{"operationId":"streamEvents","tags":["Events"],"summary":"Stream workspace events (SSE)","description":"Opens a Server-Sent Events stream of workspace events. Event payloads follow the `WorkspaceEvent` schema (see `#/components/schemas/WorkspaceEvent`). Scopes are checked per subscribed event type: `session.*` requires `torqee:sessions:read`, `transcript.*` requires `torqee:transcripts:read`. When `filters` is omitted, only lifecycle events (`session.created`, `session.status_changed`) allowed by the granted scopes are delivered; no 403 is returned in that case. Delivery is best-effort: events emitted while disconnected are lost. Reconcile via the REST API after reconnecting.","security":[{"oauth2":[]},{"apiKey":[]}],"parameters":[{"in":"query","name":"filters","required":false,"schema":{"type":"string"},"description":"URL-encoded JSON array of subscription entries (max 20, OR-matched). Structure: `#/components/schemas/EventStreamFilters`. `transcript.segment.created` entries require `sessionId`."}],"responses":{"200":{"description":"SSE stream. Each event has `event: <type>` and JSON `data` matching `WorkspaceEvent`. Heartbeat comments (`: ping`) are sent periodically.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Malformed filters, or filter cost exceeds the budget","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"error":{"type":"string","const":"invalid_filters"}},"required":["error"]},{"type":"object","properties":{"error":{"type":"string","const":"filter_cost_exceeded"},"cost":{"type":"number"},"budget":{"type":"number"},"entries":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["session.created","session.status_changed","transcript.segment.created"]},"sessionId":{"type":"string","minLength":1},"cost":{"type":"number"}},"required":["type","cost"],"additionalProperties":false}}},"required":["error","cost","budget","entries"]}]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]}},"required":["error"]}}}},"403":{"description":"Membership revoked or insufficient scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_scope","forbidden"]}},"required":["error"]}}}},"429":{"description":"Too many concurrent connections for the workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["connection_limit"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["internal_server_error"]}},"required":["error"]}}}}}}},"/api/v1/sessions":{"get":{"operationId":"listSessions","tags":["Sessions"],"summary":"List sessions","description":"Returns sessions in the workspace, newest first. Requires the `torqee:sessions:read` scope.","security":[{"oauth2":["torqee:sessions:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Paginated session summaries","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","label","memo","status","startedAt","endedAt","createdAt","updatedAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]}}}},"400":{"description":"Invalid pagination parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_request"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]}},"required":["error"]}}}},"403":{"description":"Membership revoked or insufficient scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_scope","forbidden"]}},"required":["error"]}}}},"404":{"description":"Tenant database could not be resolved for the workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["workspace_not_found"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["internal_server_error"]}},"required":["error"]}}}}},"parameters":[{"in":"query","name":"cursor","schema":{"type":"string","minLength":1}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100}}]}},"/api/v1/sessions/{id}":{"get":{"operationId":"getSession","tags":["Sessions"],"summary":"Get a session","description":"Returns session metadata without transcript segments. Requires the `torqee:sessions:read` scope.","security":[{"oauth2":["torqee:sessions:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Session metadata","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"memo":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","label","memo","status","startedAt","endedAt","createdAt","updatedAt"]}},"required":["session"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]}},"required":["error"]}}}},"403":{"description":"Membership revoked or insufficient scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_scope","forbidden"]}},"required":["error"]}}}},"404":{"description":"Session not found, or tenant database could not be resolved","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_found","workspace_not_found"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["internal_server_error"]}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/api/v1/sessions/{id}/transcript":{"get":{"operationId":"getSessionTranscript","tags":["Transcripts"],"summary":"Get a session transcript","description":"Returns all transcript segments for a session. Requires the `torqee:transcripts:read` scope.","security":[{"oauth2":["torqee:transcripts:read"]},{"apiKey":[]}],"responses":{"200":{"description":"All transcript segments for the session","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"transcript":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sequence":{"type":"number"},"timestampStart":{"type":"number"},"timestampEnd":{"type":"number"},"speakerLabel":{"anyOf":[{"type":"string"},{"type":"null"}]},"text":{"type":"string"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}]},"createdAt":{"type":"string"}},"required":["id","sequence","timestampStart","timestampEnd","speakerLabel","text","confidence","createdAt"]}}},"required":["sessionId","transcript"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]}},"required":["error"]}}}},"403":{"description":"Membership revoked or insufficient scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_scope","forbidden"]}},"required":["error"]}}}},"404":{"description":"Session not found, or tenant database could not be resolved","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_found","workspace_not_found"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["internal_server_error"]}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/api/v1/transcripts/search":{"get":{"operationId":"searchTranscripts","tags":["Transcripts"],"summary":"Search transcripts","description":"Searches transcript text in the workspace and returns matching sessions with snippets. Requires the `torqee:transcripts:read` scope.","security":[{"oauth2":["torqee:transcripts:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Sessions whose transcripts match the query, with snippets","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"endedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string"},"snippet":{"type":"string"}},"required":["id","label","status","startedAt","endedAt","createdAt","snippet"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items","nextCursor"]}}}},"400":{"description":"Invalid search parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_request"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]}},"required":["error"]}}}},"403":{"description":"Membership revoked or insufficient scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_scope","forbidden"]}},"required":["error"]}}}},"404":{"description":"Tenant database could not be resolved for the workspace","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["workspace_not_found"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["internal_server_error"]}},"required":["error"]}}}}},"parameters":[{"in":"query","name":"query","schema":{"type":"string","minLength":1},"required":true},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100}}]}},"/api/v1/sessions/{sessionId}/boards":{"get":{"operationId":"listSessionBoards","tags":["Boards"],"summary":"List session boards","description":"Returns AI-generated board contents for a session. Requires the `torqee:boards:read` scope.","security":[{"oauth2":["torqee:boards:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Board contents generated for the session","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"boardId":{"type":"string"},"version":{"type":"number"},"status":{"type":"string"},"isCurrent":{"type":"boolean"},"sourceRevisionKind":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","boardId","version","status","isCurrent","sourceRevisionKind","createdAt"]}}},"required":["items"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]}},"required":["error"]}}}},"403":{"description":"Membership revoked or insufficient scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_scope","forbidden"]}},"required":["error"]}}}},"404":{"description":"Session not found, or tenant database could not be resolved","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_found","workspace_not_found"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["internal_server_error"]}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true}]}},"/api/v1/sessions/{sessionId}/boards/{boardSpecId}":{"get":{"operationId":"getSessionBoard","tags":["Boards"],"summary":"Get a session board","description":"Returns the current AI-generated board content for a session and board spec. The `payload` field is free-form JSON whose shape depends on the board definition. Requires the `torqee:boards:read` scope.","security":[{"oauth2":["torqee:boards:read"]},{"apiKey":[]}],"responses":{"200":{"description":"Current board content for the session and board spec","content":{"application/json":{"schema":{"type":"object","properties":{"board":{"type":"object","properties":{"id":{"type":"string"},"boardId":{"type":"string"},"version":{"type":"number"},"status":{"type":"string"},"isCurrent":{"type":"boolean"},"sourceRevisionKind":{"type":"string"},"createdAt":{"type":"string"},"payload":{"description":"Free-form JSON whose shape depends on the board definition"},"payloadHash":{"type":"string"}},"required":["id","boardId","version","status","isCurrent","sourceRevisionKind","createdAt","payload","payloadHash"]}},"required":["board"]}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["unauthorized"]}},"required":["error"]}}}},"403":{"description":"Membership revoked or insufficient scope","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["insufficient_scope","forbidden"]}},"required":["error"]}}}},"404":{"description":"Session or board content not found, or tenant database could not be resolved","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["not_found","workspace_not_found"]}},"required":["error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["internal_server_error"]}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true},{"schema":{"type":"string"},"in":"path","name":"boardSpecId","required":true}]}}}}