Skip to main content
POST
Create chat

Authorizations

Authorization
string
header
required

API token from cargo-ai login. Send as Authorization: Bearer <token>.

Headers

Idempotency-Key
string

Client-generated key that makes this write safe to retry. Reusing the same key with the same request returns the original response instead of creating a second record. Reusing it with a different request returns 422. A concurrent retry while the first request is still running returns 409. Keys expire after 24 hours. Not accepted on multipart file uploads. Optional: a request without one is processed as it always was.

Maximum string length: 255
Example:

"8e03978e-40d5-43e8-bc93-6894a57f9324"

Body

application/json

Request body schema.

trigger
Trigger · object
required

Trigger configuration for the chat.

name
string

Chat name.

Required string length: 1 - 255
uuid
string<uuid>

Chat identifier. When omitted, one is generated on the server.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
agentUuid
string<uuid>

Agent identifier for the chat.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
releaseUuid
string<uuid>

Release identifier for the chat.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$
heartbeat
Heartbeat · object

Optional heartbeat configuration. When set, the chat keeps waking itself up every intervalMinutes minutes, re-sending the prompt, until it reaches maxMessages messages.

evaluator
Evaluator · object

Optional evaluator configuration (rubric + quality threshold). When set, the heartbeat loop grades each output and keeps iterating until the score reaches the threshold or maxMessages is hit.

harnessSlug
enum<string>

Optional coding-agent runtime. When set, this chat is driven by the harness instead of streamText. When omitted, later turns use the agent's pinned release, if any.

Available options:
claudeCode,
codex,
openCode,
deepAgents
repository
Repository · object

Optional git workspace for a coding harness. Unbound chats are allowed.

Response

Create chat

chat
Chat · object
required

Created chat details.