communicate-so Chat API

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