API REFERENCE

Get Chats

On this page

GET/api/chats

Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/chats' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

artist_account_idstring

Optional. Filter chats to only include those whose owning session's artistId matches the supplied artist account id. Combine with account_id to scope by both owner and artist.

account_idstring

Filter to a specific account. Only applicable when the authenticated account has access to multiple accounts via organization membership.

Responses

200Chats retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success"

chatsarray<ChatRoom>required

Array of chat objects

Item properties

idstringrequired

Chat id.

format: uuid

titlestringrequired

Display title for the chat.

accountIdstringrequired

Owning account for this chat.

format: uuid

sessionIdstringrequired

Session that owns this chat. Combine with id to build the chat URL: /sessions/{sessionId}/chats/{id}.

format: uuid

updatedAtstringrequired

ISO timestamp of the last update.

format: date-time

artistIdstringnullable

Artist account id this chat's session was created in the context of, or null when no artist was associated. Inherited from sessions.artist_id on the owning session.

format: uuid

400Bad request - invalid query parameters

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

401Unauthorized - invalid or missing API key

application/json

errorintegerrequired

format: int32

messagestringrequired

403Forbidden - account_id is not a member of the organization or account tried to filter by an account_id they don't have access to

application/json

errorintegerrequired

format: int32

messagestringrequired

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download research.json

View operation source

json

{
  "description": "Returns chats for the authenticated account. Personal Bearer tokens see only the caller's chats; org keys see chats across the org's member accounts; admin keys see all chats. Each row carries the chat id and the session id needed to build the chat URL.",
  "parameters": [
    {
      "name": "artist_account_id",
      "in": "query",
      "description": "Optional. Filter chats to only include those whose owning session's `artistId` matches the supplied artist account id. Combine with `account_id` to scope by both owner and artist.",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "account_id",
      "in": "query",
      "description": "Filter to a specific account. Only applicable when the authenticated account has access to multiple accounts via organization membership.",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Chats retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GetChatsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid query parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GetChatsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - account_id is not a member of the organization or account tried to filter by an account_id they don't have access to",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}