Messages
Submit a message and start (or continue) an agent turn
Reserves credit admission, persists the user message, and dispatches a durable Trigger.dev turn. One active run per chat is enforced — a second send while a run is active returns 409 CONFLICT. Idempotent per send:{chatId}:{messageId} (00-master-spec.md §4).
POST
/
api
/
v1
/
chats
/
{chatId}
/
messages
Error
A valid request URL is required to generate request examples{
"chatId": "<string>",
"message": {
"id": "<string>",
"chatId": "<string>",
"role": "user",
"status": "streaming",
"content": [
{
"type": "text",
"text": "<string>"
}
],
"attachments": [
{
"id": "<string>",
"chatId": "<string>",
"messageId": "<string>",
"orderIndex": 1,
"status": "PENDING",
"mimeType": "<string>",
"byteSize": 1,
"fileName": "<string>",
"resultUrl": "<string>",
"errorCode": "<string>",
"errorMessage": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"source": "uploaded"
}
],
"createdAt": "<string>"
},
"run": {
"id": "<string>",
"chatId": "<string>",
"status": "queued",
"userMessageId": "<string>",
"assistantMessageId": "<string>",
"lastStreamIndex": 123,
"cancelRequestedAt": "<string>",
"requestedModel": "<string>",
"resolvedModel": "<string>",
"errorCode": "<string>",
"errorMessage": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"startedAt": "<string>",
"finishedAt": "<string>",
"toolInvocations": [
{
"id": "<string>",
"agentRunId": "<string>",
"turnIndex": 1,
"callIndex": 1,
"toolCallId": "<string>",
"name": "<string>",
"nodeType": "<string>",
"input": {},
"status": "DISPATCHING",
"creditEstimate": 1,
"creditUsed": 1,
"resultUrls": [
"<string>"
],
"errorCode": "<string>",
"errorMessage": "<string>",
"startedAt": "<string>",
"finishedAt": "<string>",
"durationMs": 1,
"createdAt": "<string>",
"updatedAt": "<string>"
}
],
"totalCreditsUsed": 1,
"pendingWaitpoint": {
"id": "<string>",
"agentRunId": "<string>",
"kind": "CREDIT_APPROVAL",
"status": "PENDING",
"requestPayload": {
"toolName": "<string>",
"estimatedCredits": 1,
"threshold": 1
},
"resolvedPayload": {
"approved": true,
"respondedAt": "<string>"
},
"expiresAt": "<string>",
"resolvedAt": "<string>"
}
},
"realtime": {
"runId": "<string>",
"streamKey": "<string>",
"accessToken": "<string>",
"expiresAt": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}Authorizations
Clerk session token, Authorization: Bearer <token>. This documents the app's own internal auth as of S1-S6 — see S8-public-api-bonus.md for the fallback scope this doc covers, and the public API-key scheme's own page once the full scope ships.
Path Parameters
Minimum string length:
1Body
application/json
⌘I
Error
A valid request URL is required to generate request examples{
"chatId": "<string>",
"message": {
"id": "<string>",
"chatId": "<string>",
"role": "user",
"status": "streaming",
"content": [
{
"type": "text",
"text": "<string>"
}
],
"attachments": [
{
"id": "<string>",
"chatId": "<string>",
"messageId": "<string>",
"orderIndex": 1,
"status": "PENDING",
"mimeType": "<string>",
"byteSize": 1,
"fileName": "<string>",
"resultUrl": "<string>",
"errorCode": "<string>",
"errorMessage": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"source": "uploaded"
}
],
"createdAt": "<string>"
},
"run": {
"id": "<string>",
"chatId": "<string>",
"status": "queued",
"userMessageId": "<string>",
"assistantMessageId": "<string>",
"lastStreamIndex": 123,
"cancelRequestedAt": "<string>",
"requestedModel": "<string>",
"resolvedModel": "<string>",
"errorCode": "<string>",
"errorMessage": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>",
"startedAt": "<string>",
"finishedAt": "<string>",
"toolInvocations": [
{
"id": "<string>",
"agentRunId": "<string>",
"turnIndex": 1,
"callIndex": 1,
"toolCallId": "<string>",
"name": "<string>",
"nodeType": "<string>",
"input": {},
"status": "DISPATCHING",
"creditEstimate": 1,
"creditUsed": 1,
"resultUrls": [
"<string>"
],
"errorCode": "<string>",
"errorMessage": "<string>",
"startedAt": "<string>",
"finishedAt": "<string>",
"durationMs": 1,
"createdAt": "<string>",
"updatedAt": "<string>"
}
],
"totalCreditsUsed": 1,
"pendingWaitpoint": {
"id": "<string>",
"agentRunId": "<string>",
"kind": "CREDIT_APPROVAL",
"status": "PENDING",
"requestPayload": {
"toolName": "<string>",
"estimatedCredits": 1,
"threshold": 1
},
"resolvedPayload": {
"approved": true,
"respondedAt": "<string>"
},
"expiresAt": "<string>",
"resolvedAt": "<string>"
}
},
"realtime": {
"runId": "<string>",
"streamKey": "<string>",
"accessToken": "<string>",
"expiresAt": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}
}