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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

sessionIdpath · stringrequired

Request bodyapplication/json

cURL for this request

curl --request POST \
  --url 'https://recoup-api.vercel.app/api/sessions/{sessionId}/chats' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "string"
}'

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"
          }
        }
      }
    }
  }
}