Chat API

Send a message and receive an assistant response. Automatically creates a session, or continues an existing one when you pass a session_id.

POST/v1/chat

Authentication

Requires a secret API key passed as a Bearer token (Authorization: Bearer carrier_sk_…).

Request body

Field	Type	Description
mode*	string	Carrier mode: general, developer, or research.
message*	string	The user message to send.
session_id	string	Continue an existing session. Omit to start a new one.

Example request

bash

curl -X POST https://api.carrieros.ai/v1/chat \
  -H "Authorization: Bearer carrier_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "developer",
    "message": "Explain OAuth in two sentences."
  }'

Response

Field	Type	Description
id	string	Identifier of the generated assistant message.
response	string	The assistant's reply.
session_id	string	Session id — reuse it to continue the conversation.
tokens_used	number	Total input + output tokens for this turn.

Example response

json

{
  "success": true,
  "data": {
    "id": "b1e2…",
    "response": "OAuth is an open standard for delegated authorization…",
    "session_id": "9c4f…",
    "tokens_used": 523
  }
}

Possible errors

Code	HTTP	When it occurs
VALIDATION_ERROR	400	mode is missing/invalid, or message is empty.
SESSION_NOT_FOUND	404	A session_id was passed that doesn't belong to this project.
USAGE_LIMIT_REACHED	402	The account's usage/credit limit has been reached.
INVALID_API_KEY	401	The key is missing, malformed, revoked, or inactive.

Notes

Modes map to internal configurations — provider models are never exposed. See Carrier Modes.

The response is non-streaming. To keep context across turns, pass the returned session_id on subsequent requests.