{"openapi":"3.1.0","info":{"title":"Communicate Public REST API","version":"1.0.0","summary":"Workspace-scoped agent listing and chat operations with least-privilege OAuth scopes.","description":"Canonical external schema for the non-streaming public REST API. Exchange a workspace API-key client ID and secret for a short-lived OAuth access token, or use the `ck_` key directly for backward compatibility. `requestId` is optional but, when supplied, becomes the idempotency key for retries of the same chat input."},"servers":[{"url":"https://app.communicate.so/api/v1","description":"Canonical external base URL served through the Next.js /api/v1 rewrite."}],"security":[{"oauth2":[]},{"bearerAuth":[]}],"paths":{"/oauth/token":{"post":{"operationId":"createAccessToken","summary":"Exchange API-key client credentials for an access token","description":"Uses HTTP Basic authentication where the API key ID is the client ID and the one-time `ck_` token is the client secret. Requested scopes must be a subset of the API key scope ceiling.","tags":["Authentication"],"security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"scope":{"type":"string","description":"Space-delimited subset of `agents:read` and `chat:write`."},"resource":{"type":"string","format":"uri","enum":["https://app.communicate.so/api/v1","https://app.communicate.so/mcp"],"default":"https://app.communicate.so/api/v1","description":"RFC 8707 resource audience. MCP tokens accept only `agents:read`."}}}}}},"responses":{"200":{"description":"Short-lived scoped bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponse"}}}},"400":{"description":"Unsupported grant or invalid scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"401":{"description":"Invalid or revoked client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"429":{"description":"Token request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}}}}},"/agents":{"get":{"operationId":"listAgents","summary":"List agents in the API key workspace","description":"Returns the agents visible to the authenticated workspace API key. This route is non-streaming and shares the public API group rate limit of 600 requests per minute per key.","tags":["Agents"],"security":[{"oauth2":["agents:read"]},{"bearerAuth":[]}],"responses":{"200":{"description":"Workspace agents","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentSummary"}}}}},"401":{"description":"Missing or invalid API key","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer challenge describing the API-key authentication failure."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential does not grant `agents:read`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"API key rate limit exceeded","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/agents/{agentId}/chat":{"post":{"operationId":"chatWithAgent","summary":"Send a chat turn to an agent","description":"Creates or continues an API-channel conversation and returns one complete response payload. This endpoint does not stream. `requestId` is optional idempotency; reusing it with different input yields `409 request_id_conflict`. Chat turns are additionally rate-limited to 60 requests per minute per key. Responses may include grounded citations and, when an action ran, `actionName`.","tags":["Chat"],"security":[{"oauth2":["chat:write"]},{"bearerAuth":[]}],"parameters":[{"name":"agentId","in":"path","required":true,"description":"The target agent identifier.","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Completed non-streaming chat response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"400":{"description":"Malformed JSON or invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer challenge describing the API-key authentication failure."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Chat generation is unavailable because billing is paused or credits are exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Credential does not grant `chat:write`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent not found in the API key workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Agent is inactive, or requestId was replayed with different input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"API key rate limit exceeded","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Agent is mid-transfer and temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"headers":{"RateLimitLimit":{"description":"Maximum requests allowed in the active one-minute window.","schema":{"type":"integer","minimum":1}},"RateLimitRemaining":{"description":"Requests remaining in the active one-minute window.","schema":{"type":"integer","minimum":0}},"RateLimitReset":{"description":"Seconds until the active rate-limit window resets.","schema":{"type":"integer","minimum":1}}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client-credentials tokens bounded by the source API key scope ceiling.","flows":{"clientCredentials":{"tokenUrl":"https://app.communicate.so/api/v1/oauth/token","scopes":{"agents:read":"List agents in the authenticated workspace.","chat:write":"Create chat turns with an agent in the authenticated workspace."}}}},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Workspace API key token with the `ck_` prefix."}},"schemas":{"OAuthTokenResponse":{"type":"object","additionalProperties":false,"required":["access_token","token_type","expires_in","scope"],"properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","const":3600},"scope":{"type":"string"}}},"OAuthErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"AgentSummary":{"type":"object","additionalProperties":false,"required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive","draft"]}}},"ChatRequest":{"type":"object","additionalProperties":false,"required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":4000,"description":"End-user prompt sent to the agent."},"requestId":{"type":"string","format":"uuid","description":"Optional idempotency key for safe retries of the same chat input."},"conversationId":{"type":["string","null"],"description":"Continue an existing API-channel conversation when present."}}},"Citation":{"type":"object","additionalProperties":false,"required":["sourceId","title","snippet","url"],"properties":{"sourceId":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string"},"url":{"type":["string","null"]}}},"ChatResponse":{"type":"object","additionalProperties":false,"required":["conversationId","messageId","userMessageId","answer","citations","mode"],"properties":{"conversationId":{"type":"string"},"ticketNumber":{"type":["integer","null"]},"messageId":{"type":"string"},"userMessageId":{"type":"string"},"answer":{"type":"string"},"citations":{"type":"array","items":{"$ref":"#/components/schemas/Citation"}},"mode":{"type":"string","enum":["ai","human"]},"actionName":{"type":"string","description":"Present when a workspace action produced the final answer."},"followUps":{"type":"array","items":{"type":"string"},"maxItems":3,"description":"Optional suggested next questions returned with the answer."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"reason":{"type":"string"},"details":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","message","path"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"}}}}}}}}}