Create Durable Turn

curl -X POST \
  "https://api.trellis.sh/v1/agents/AGENT_ID/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb/turns" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "mobile-20260808-7f4f1fca",
    "message": "How many orders were placed last month?",
    "integration_id": "INTEGRATION_ID",
    "model": "claude-sonnet-5",
    "scoped_project_ids": []
  }'

import requests

response = requests.post(
    "https://api.trellis.sh/v1/agents/AGENT_ID/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb/turns",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "client_request_id": "mobile-20260808-7f4f1fca",
        "message": "How many orders were placed last month?",
        "integration_id": "INTEGRATION_ID",
        "model": "claude-sonnet-5",
        "scoped_project_ids": [],
    },
)
response.raise_for_status()
accepted = response.json()

const response = await fetch(
  "https://api.trellis.sh/v1/agents/AGENT_ID/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb/turns",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      client_request_id: "mobile-20260808-7f4f1fca",
      message: "How many orders were placed last month?",
      integration_id: "INTEGRATION_ID",
      model: "claude-sonnet-5",
      scoped_project_ids: [],
    }),
  },
);
const accepted = await response.json();

{
  "turn_id": "26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b",
  "chat_id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  "user_message_id": "b3ebae7f-e265-47e4-92dd-344d396f0c33",
  "status": "in_progress",
  "created_at": "2026-08-08T18:00:01.234567+00:00"
}

{"detail":{"code":"IDEMPOTENCY_CONFLICT"}}

{"detail":{"code":"TURN_ALREADY_RUNNING"}}

{"detail":"Integration not found"}

{"detail":"Chat not found"}

{"code":"RATE_LIMIT","retry_after_seconds":7}

Starts a durable turn and returns immediately with 202 Accepted. The agent continues server-side after the request ends; poll Get Turn until status is terminal.

POST /v1/agents/{agent_id}/chats/{chat_id}/turns

string

required

Bearer token obtained from Authenticate.

string

required

Published agent UUID. Use the chat’s agent_id; for a legacy null binding, use your organization’s configured published agent UUID rather than inferring it from display name or is_trellis_default.

string

required

Existing member-owned chat UUID. There is no lazy chat creation.

Request body

string

required

Idempotency key, 1–128 characters. Retrying the same semantic payload returns the original turn. Reusing the ID for a different payload returns 409 IDEMPOTENCY_CONFLICT.

string

required

Non-empty user message.

string

Database integration for this and later turns. A valid change persists on the chat. A malformed, unknown, or out-of-organization ID returns 400 Integration not found; see the idempotency recovery note below.

string

Model override for this turn. Populate choices from List Models.

string[]

Upload IDs from Upload Files.

string

Execute a stored query before agent generation. A database integration must be bound.

object

Saved-query parameters with string values.

string[]

Project scope to persist. Omit the field to retain the stored scope; send [] to clear it. In request order, the server keeps the first occurrence of each valid, organization-owned, permitted project and persists at most the first two surviving IDs. Duplicate, malformed, unknown, out-of-organization, non-permitted, and additional IDs are silently discarded.

string

Legacy shorthand for a one-element scoped_project_ids. Ignored when the array field is present.

Compatibility-only fields

The request model accepts these fields for parity with internal/legacy transports. New external clients should avoid them:

Field	Type	Behavior
`connection_id`	string	Legacy integration alias unless `connection_type` is `"project"`; prefer `integration_id`
`connection_type`	string	Legacy datasource discriminator
`attached_files`	object[]	Internal project-file references; external clients should use `upload_ids`
`open_schedule`	object	Internal schedule handoff that replaces normal generation
`title`	string	Does not retitle the required existing chat
`voice_mode`	boolean	Ignored and forced to `false` on the external REST route

Response

string

required

Durable turn UUID.

string

required

Owning chat UUID.

string | null

required

Persisted user-message UUID.

string

required

in_progress for a newly accepted turn. An idempotent replay can return the original turn’s current status: in_progress, completed, failed, or cancelled.

string

required

ISO 8601 acceptance timestamp.

Idempotency and concurrency

Same client_request_id and same semantic payload: returns the original turn; no second user message is written.
Same ID and different payload: 409 with detail.code: "IDEMPOTENCY_CONFLICT".
Another running turn on the chat: 409 with detail.code: "TURN_ALREADY_RUNNING".

Generate a new request ID whenever any generation input changes, including the message, model, integration, scope, uploads, saved query, or parameters.

Datasource binding happens after the durable turn is accepted and its user message and idempotency record are persisted. If integration_id is invalid, the server terminalizes that turn and returns 400, so the supplied client_request_id has already been consumed by the failed attempt. Retrying the unchanged request returns the original failed turn; correcting integration_id under the same key returns 409 IDEMPOTENCY_CONFLICT. Correct the integration and submit with a fresh client_request_id.

This route shares a single per-member budget with WebSocket send_message and edit_message: 10 submissions per minute and 3 per 10 seconds combined. A 429 response includes Retry-After; re-authentication does not reset the budget.

curl -X POST \
  "https://api.trellis.sh/v1/agents/AGENT_ID/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb/turns" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_request_id": "mobile-20260808-7f4f1fca",
    "message": "How many orders were placed last month?",
    "integration_id": "INTEGRATION_ID",
    "model": "claude-sonnet-5",
    "scoped_project_ids": []
  }'

import requests

response = requests.post(
    "https://api.trellis.sh/v1/agents/AGENT_ID/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb/turns",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "client_request_id": "mobile-20260808-7f4f1fca",
        "message": "How many orders were placed last month?",
        "integration_id": "INTEGRATION_ID",
        "model": "claude-sonnet-5",
        "scoped_project_ids": [],
    },
)
response.raise_for_status()
accepted = response.json()

const response = await fetch(
  "https://api.trellis.sh/v1/agents/AGENT_ID/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb/turns",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      client_request_id: "mobile-20260808-7f4f1fca",
      message: "How many orders were placed last month?",
      integration_id: "INTEGRATION_ID",
      model: "claude-sonnet-5",
      scoped_project_ids: [],
    }),
  },
);
const accepted = await response.json();

{
  "turn_id": "26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b",
  "chat_id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  "user_message_id": "b3ebae7f-e265-47e4-92dd-344d396f0c33",
  "status": "in_progress",
  "created_at": "2026-08-08T18:00:01.234567+00:00"
}

{"detail":{"code":"IDEMPOTENCY_CONFLICT"}}

{"detail":{"code":"TURN_ALREADY_RUNNING"}}

{"detail":"Integration not found"}

{"detail":"Chat not found"}

{"code":"RATE_LIMIT","retry_after_seconds":7}

Overview

Authentication

Agents

Datasources

Saved Queries

Models

Chats

Artifacts

Jobs

Voice

Audio

User Memories

Organization Rules

Admin

Request body

Compatibility-only fields

Response

Idempotency and concurrency

​Request body

​Compatibility-only fields

​Response

​Idempotency and concurrency

Request body

Compatibility-only fields

Response

Idempotency and concurrency