API REFERENCE

Create Session Chat

On this page

POST/api/sessions/{sessionId}/chats

Creates a new chat inside the given session. Callers may pass { id } to claim a deterministic chat id — useful for optimistic UI flows where the client generates the id locally and then persists it. If a chat with that id already exists in this session the call is idempotent and returns the existing row; if it exists in another session, 409 is returned.

Authentication

x-api-key in header

BearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/sessions/YOUR_SESSION_ID/chats' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "string"
}'

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

Parameters

Path parameters

sessionIdstringrequired

The id of the parent session.

Request body

application/json

idstring

Optional client-supplied chat id (used for optimistic UI flows). When omitted, the server generates a UUID. When supplied, must be a non-empty string.

minLength: 1

Responses

200Chat created, or existing chat returned (idempotent on same-session reuse).

application/json

chatobjectrequired

Properties

idstringrequired

Chat id (nanoid).

sessionIdstringrequired

Owning session id.

titlestringrequired

Display title for the chat. The initial chat created with a session is titled New chat.

modelIdstringrequired

AI Gateway model identifier the chat is configured to use (e.g. openai/gpt-5.4).

activeStreamIdstringnullable

Id of an in-flight assistant stream, if one is active.

lastAssistantMessageAtstringnullable

Timestamp of the most recent assistant message in this chat.

format: date-time

createdAtstringrequired

format: date-time

updatedAtstringrequired

format: date-time

400Invalid chat id — body contained id but it was an empty string or not a string.

application/json

errorstring · enumrequired

Values: "Invalid chat id"

401Unauthorized — invalid or missing API key / Bearer token.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

403Forbidden — the authenticated account does not own this session.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

404Not found — no session exists with the given id.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

409Chat id conflict — a chat with the requested id already exists on a different session.

application/json

errorstring · enumrequired

Values: "Chat ID conflict"

500Server error — the chat could not be persisted.

application/json

statusstring · enumrequired

Always "error" for error responses.

Values: "error"

errorstringrequired

Human-readable error message.

Full specification

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

Download sessions.json

View operation source

json

{
  "summary": "Create session chat",
  "description": "Creates a new chat inside the given session. Callers may pass `{ id }` to claim a deterministic chat id — useful for optimistic UI flows where the client generates the id locally and then persists it. If a chat with that id already exists in **this** session the call is idempotent and returns the existing row; if it exists in **another** session, 409 is returned.",
  "parameters": [
    {
      "name": "sessionId",
      "in": "path",
      "required": true,
      "description": "The id of the parent session.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateSessionChatRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Chat created, or existing chat returned (idempotent on same-session reuse).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateSessionChatResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid chat id — body contained `id` but it was an empty string or not a string.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InvalidChatIdError"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key / Bearer token.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden — the authenticated account does not own this session.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Not found — no session exists with the given id.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Chat id conflict — a chat with the requested id already exists on a different session.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ChatIdConflictError"
          }
        }
      }
    },
    "500": {
      "description": "Server error — the chat could not be persisted.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}