API REFERENCE

Create Chat

On this page

POST/api/chats

Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to.

Authentication

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

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/chats' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "artistId": "YOUR_ID",
  "chatId": "YOUR_ID",
  "accountId": "YOUR_ID",
  "topic": "string"
}'

Request body

Chat creation parameters

application/json

artistIdstring

UUID of the artist account the chat is associated with

format: uuid

chatIdstring

UUID for the new chat (client-generated). If not provided, one will be generated automatically.

format: uuid

accountIdstring

UUID of the account to create the chat for. Only applicable when the authenticated account has access to multiple accounts via organization membership. If not provided, the chat is created for the API key's own account.

format: uuid

topicstring

Topic name for the new chat room (e.g., 'Pulse Feb 2'). To edit the topic of an existing room, use PATCH /api/chats.

Responses

200Chat created successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success"

chatobjectrequired

The created chat room object

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 - failed to create chat

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

403Forbidden - API key does not have access to the specified accountId

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

Full specification

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

Download research.json

View operation source

json

{
  "description": "Create a new chat room. Optionally associate it with an artist and/or provide a client-generated chat ID. Pass accountId to create a chat on behalf of a specific account the API key has access to.",
  "requestBody": {
    "description": "Chat creation parameters",
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateChatRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Chat created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateChatResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - failed to create chat",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateChatErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - API key does not have access to the specified accountId",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateChatErrorResponse"
          }
        }
      }
    }
  }
}