communicate-so Chat API
The Chat API from communicate-so — 1 operation(s) for chat.
The Chat API from communicate-so — 1 operation(s) for chat.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/communicate-so:communicate-so-chat-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Communicate So Chat API
version: 0.1.5
description: 'Operations tagged Chat across 2 of this provider''s published API definitions: communicate-so-openapi.json, communicate-so-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.communicate.so/api/v1
description: Canonical external base URL served through the Next.js /api/v1 rewrite.
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Chat
paths:
/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'
servers:
- url: https://app.communicate.so/api/v1
description: Canonical external base URL served through the Next.js /api/v1 rewrite.
components:
headers:
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
RateLimitLimit:
description: Maximum requests allowed in the active one-minute window.
schema:
type: integer
minimum: 1
schemas:
Citation:
type: object
additionalProperties: false
required:
- sourceId
- title
- snippet
- url
properties:
sourceId:
type: string
title:
type: string
snippet:
type: string
url:
type:
- string
- 'null'
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
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.
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.
securitySchemes:
accountSession:
type: apiKey
in: cookie
name: __Secure-better-auth.session_token
description: Signed Better Auth session cookie for an HTTPS application origin. Credential management additionally requires verified email and fresh password proof on writes.
localAccountSession:
type: apiKey
in: cookie
name: better-auth.session_token
description: Signed session cookie used when the configured application auth origin is HTTP, such as local development.
accountBearer:
type: http
scheme: bearer
bearerFormat: Account credential
description: Opaque user-bound `ca_` account credential. Each request checks live account scopes, verified email, expiry, revocation and the issuer session. Not a workspace `ck_` key or OAuth access token.
clientCredentialsBasic:
type: http
scheme: basic
description: Use the API key ID as the username and the one-time `ck_` API key token as the password.
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.
x-refined-from:
- communicate-so-openapi.json
- communicate-so-openapi.json