# Introduction URL: https://developers.torqee.app/docs torqee Connect is a read-only public API and MCP server for workspace data. It is designed for external agents, internal automation, and developer tools that need to inspect torqee activity without changing it. The API exposes sessions, transcript segments, AI board contents, and realtime workspace events. Every credential is scoped to one workspace, so a token or API key can only read data that belongs to its own workspace. Base URL: `https://connect.torqee.app` Machine-readable API contract: `https://connect.torqee.app/openapi.json` Scopes \[#scopes] | Scope | Allows | | ------------------------- | ------------------------------------------------ | | `torqee:sessions:read` | List sessions and read session metadata. | | `torqee:transcripts:read` | Search transcripts and read transcript segments. | | `torqee:boards:read` | List and read AI board contents. | You can authenticate with either a `torqee_` API key or an OAuth 2.1 access token. Both credential types carry the same read scopes. # Quickstart URL: https://developers.torqee.app/docs/quickstart This path uses an API key because it is the shortest way to confirm that your workspace can be read from an external tool. 1\. Create an API key \[#1-create-an-api-key] Open the torqee web app, go to workspace settings, and create a Connect API key. Copy the `torqee_` value once and store it in your secret manager. API keys grant read access to workspace data. Treat them like production credentials and never commit them to source control. 2\. Make your first request \[#2-make-your-first-request] ```bash curl https://connect.torqee.app/api/v1/sessions \ -H "Authorization: Bearer torqee_YOUR_API_KEY" ``` A successful response returns sessions from the workspace that owns the key. Use the OpenAPI reference for pagination, response fields, and operation-level scope requirements. 3\. Connect an MCP client \[#3-connect-an-mcp-client] Connect clients that support Streamable HTTP to the MCP endpoint: ```bash claude mcp add --transport http torqee https://connect.torqee.app/mcp ``` If your MCP client does not run OAuth discovery, configure the same API key as a Bearer token: ```json { "mcpServers": { "torqee": { "type": "http", "url": "https://connect.torqee.app/mcp", "headers": { "Authorization": "Bearer torqee_YOUR_API_KEY" } } } } ``` # Errors URL: https://developers.torqee.app/docs/guides/errors Error responses use a JSON object with an `error` code: ```json { "error": "unauthorized" } ``` Some errors include extra fields, such as `filter_cost_exceeded`. | HTTP status | Code | Meaning | Action | | ----------- | ----------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | 400 | `invalid_request` | Query parameters or request shape failed validation. | Check the API reference and retry with valid parameters. | | 400 | `invalid_filters` | The SSE `filters` value is not valid URL-encoded JSON or does not match the filter schema. | Encode a JSON array of filter entries. Include `sessionId` for `transcript.segment.created`. | | 400 | `filter_cost_exceeded` | The SSE filters are valid but exceed the cost budget. | Reduce the number of entries or split subscriptions. | | 401 | `unauthorized` | Bearer token is missing, invalid, expired, lacks `workspace_id`, or the API key is invalid. | Send a valid OAuth token or `torqee_` API key. | | 403 | `forbidden` | The issuer is no longer an active member of the workspace. | Reauthorize or restore workspace membership. | | 403 | `insufficient_scope` | The credential does not include the scope required by the endpoint, event type, or MCP tool. | Request or issue a credential with the required read scope. | | 404 | `not_found` | The requested session or board content does not exist. | Verify the resource ID belongs to the credential workspace. | | 404 | `workspace_not_found` | Connect could not resolve the tenant database for the credential workspace. | Check workspace provisioning and contact torqee support if it persists. | | 429 | `connection_limit` | The workspace has too many concurrent SSE streams. | Close unused streams and reconnect with backoff. | | 500 | `internal_server_error` | An unexpected server error occurred. | Retry later; internal details are not exposed in the response. | # Realtime Events URL: https://developers.torqee.app/docs/guides/realtime-events Realtime events are delivered from: ```text GET https://connect.torqee.app/api/v1/events/stream ``` The response is `text/event-stream`. Each event has `event: ` and JSON `data` matching the `WorkspaceEvent` schema in the OpenAPI spec. Event types \[#event-types] | Event type | Required scope | | ---------------------------- | ------------------------- | | `session.created` | `torqee:sessions:read` | | `session.status_changed` | `torqee:sessions:read` | | `transcript.segment.created` | `torqee:transcripts:read` | When `filters` is omitted, Connect subscribes to lifecycle events (`session.created` and `session.status_changed`) and filters them by the scopes the credential already has. Filters \[#filters] The `filters` query parameter is a URL-encoded JSON array. Entries are OR-matched. Each entry has a `type`, and `transcript.segment.created` also requires `sessionId`. ```json [ { "type": "session.created" }, { "type": "session.status_changed" }, { "type": "transcript.segment.created", "sessionId": "session_123" } ] ``` ```bash curl -N "https://connect.torqee.app/api/v1/events/stream?filters=%5B%7B%22type%22%3A%22session.created%22%7D%5D" \ -H "Authorization: Bearer torqee_YOUR_API_KEY" ``` Browser `EventSource` cannot set an `Authorization` header directly. Use an SSE client that supports headers, or stream the response with `fetch`: ```ts const response = await fetch( "https://connect.torqee.app/api/v1/events/stream", { headers: { Authorization: "Bearer torqee_YOUR_API_KEY" }, }, ); const reader = response.body?.getReader(); ``` Cost and limits \[#cost-and-limits] Filters are limited to 20 entries. Each entry costs 10, and the current budget is 100. Requests above the budget return: ```json { "error": "filter_cost_exceeded", "cost": 110, "budget": 100, "entries": [ { "type": "session.created", "cost": 10 }, { "type": "session.status_changed", "cost": 10 } ] } ``` Too many concurrent streams for the same workspace return: ```json { "error": "connection_limit" } ``` Event delivery is best-effort. Events emitted while the client is disconnected are not replayed. Reconnect with backoff and reconcile missed state through the REST API. Payload example \[#payload-example] ```json { "type": "session.created", "sessionId": "session_123", "occurredAt": "2026-07-06T00:00:00.000Z", "data": { "sessionId": "session_123", "occurredAt": "2026-07-06T00:00:00.000Z", "session": { "id": "session_123", "label": "Discovery call", "memo": null, "status": "recording", "startedAt": "2026-07-06T00:00:00.000Z", "endedAt": null, "createdAt": "2026-07-06T00:00:00.000Z", "updatedAt": "2026-07-06T00:00:00.000Z" } } } ``` # Connecting URL: https://developers.torqee.app/docs/mcp torqee Connect exposes an MCP Streamable HTTP endpoint at: ```text https://connect.torqee.app/mcp ``` The endpoint is stateless on the server side. Each request authenticates with the same workspace-scoped Bearer credentials used by the REST API. OAuth discovery \[#oauth-discovery] MCP clients that support protected resource discovery can start with the MCP URL and follow Connect metadata to the torqee authorization server. ```bash claude mcp add --transport http torqee https://connect.torqee.app/mcp ``` API key header \[#api-key-header] Clients that do not run OAuth discovery can send a `torqee_` API key as a Bearer token: ```json { "mcpServers": { "torqee": { "type": "http", "url": "https://connect.torqee.app/mcp", "headers": { "Authorization": "Bearer torqee_YOUR_API_KEY" } } } } ``` API keys and OAuth tokens are both workspace scoped and use the same read scopes. # Tools URL: https://developers.torqee.app/docs/mcp/tools | Tool | Required scope | Input | Description | | -------------------- | ------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `list_sessions` | `torqee:sessions:read` | `limit?`, `cursor?` | List paginated session summaries. | | `get_session` | `torqee:sessions:read` | `sessionId` | Get metadata for a specific session. Use `get_transcript` to retrieve transcript segments. | | `search_transcripts` | `torqee:transcripts:read` | `query`, `limit?` | Search transcript text and return matching sessions with snippets. | | `get_transcript` | `torqee:transcripts:read` | `sessionId` | Get transcript segments for a specific session. | | `list_boards` | `torqee:boards:read` | `sessionId` | List all board contents for a given session. Boards contain AI-generated analysis results such as summaries and action items. | | `get_board` | `torqee:boards:read` | `sessionId`, `boardSpecId` | Get the current board content for a specific session and board spec. Returns the full payload of the board. | When the credential is valid but lacks a required scope, the tool result has `isError: true` and text content containing: ```json { "error": "insufficient_scope" } ``` # API Keys URL: https://developers.torqee.app/docs/authentication/api-keys API keys are `torqee_`-prefixed Bearer tokens for trusted server-side integrations and agents. ```bash curl https://connect.torqee.app/api/v1/sessions \ -H "Authorization: Bearer torqee_YOUR_API_KEY" ``` API keys are issued and revoked in the torqee web app. Connect validates keys but does not create them. An API key carries the same read scopes as OAuth tokens: | Scope | Allows | | ------------------------- | ------------------------------------------------ | | `torqee:sessions:read` | List sessions and read session metadata. | | `torqee:transcripts:read` | Search transcripts and read transcript segments. | | `torqee:boards:read` | List and read AI board contents. | Keep API keys secret. They grant read access to workspace data for their configured scopes. # Authentication URL: https://developers.torqee.app/docs/authentication torqee Connect accepts Bearer credentials on every REST and MCP request except public metadata endpoints. | Method | Best for | How it works | | --------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | API keys | Server-to-server jobs, agents, and trusted backend tools. | A `torqee_` key is issued from the torqee web app and sent as a Bearer token. | | OAuth 2.1 | User-facing integrations that need explicit end-user consent. | The client runs authorization code with PKCE against torqee Auth and requests Connect as the protected resource. | Both methods are workspace scoped. A credential reads only the workspace it was issued for, and only the scopes granted to that credential. Use API keys when you operate the integration yourself. Use OAuth when another user or organization authorizes your app. # OAuth 2.1 URL: https://developers.torqee.app/docs/authentication/oauth OAuth clients use authorization code with PKCE. The authorization server is `https://auth.torqee.app`, and its OAuth endpoints include the BetterAuth base path: | Endpoint | URL | | ------------- | --------------------------------------------------- | | Authorization | `https://auth.torqee.app/api/auth/oauth2/authorize` | | Token | `https://auth.torqee.app/api/auth/oauth2/token` | Resource indicator \[#resource-indicator] When requesting authorization, include the RFC 8707 `resource` parameter: ```text resource=https://connect.torqee.app ``` Connect validates the access token audience against that resource. Tokens issued for another audience are rejected. Protected resource discovery \[#protected-resource-discovery] When a request has no valid Bearer credential, Connect returns a 401 response with a `WWW-Authenticate` header pointing at protected resource metadata: ```http WWW-Authenticate: Bearer resource_metadata="https://connect.torqee.app/.well-known/oauth-protected-resource" ``` Fetch the metadata endpoint to discover the resource, authorization server, and supported scopes: ```json { "resource": "https://connect.torqee.app", "authorization_servers": ["https://auth.torqee.app/api/auth"], "scopes_supported": [ "torqee:sessions:read", "torqee:transcripts:read", "torqee:boards:read" ] } ``` Scopes \[#scopes] Request only the scopes your integration needs: | Scope | Allows | | ------------------------- | ------------------------------------------------ | | `torqee:sessions:read` | List sessions and read session metadata. | | `torqee:transcripts:read` | Search transcripts and read transcript segments. | | `torqee:boards:read` | List and read AI board contents. | If a token is valid but does not include the required scope, Connect returns `403 { "error": "insufficient_scope" }`. # Stream workspace events (SSE) URL: https://developers.torqee.app/docs/api-reference/events/streamEvents {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} 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. # Get a session board URL: https://developers.torqee.app/docs/api-reference/boards/getSessionBoard {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} 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. # List session boards URL: https://developers.torqee.app/docs/api-reference/boards/listSessionBoards {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Returns AI-generated board contents for a session. Requires the `torqee:boards:read` scope. # Get a session URL: https://developers.torqee.app/docs/api-reference/sessions/getSession {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Returns session metadata without transcript segments. Requires the `torqee:sessions:read` scope. # List sessions URL: https://developers.torqee.app/docs/api-reference/sessions/listSessions {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Returns sessions in the workspace, newest first. Requires the `torqee:sessions:read` scope. # Get a session transcript URL: https://developers.torqee.app/docs/api-reference/transcripts/getSessionTranscript {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Returns all transcript segments for a session. Requires the `torqee:transcripts:read` scope. # Search transcripts URL: https://developers.torqee.app/docs/api-reference/transcripts/searchTranscripts {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Searches transcript text in the workspace and returns matching sessions with snippets. Requires the `torqee:transcripts:read` scope.