Get Chat

curl "https://api.trellis.sh/v1/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests

response = requests.get(
    "https://api.trellis.sh/v1/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
chat = response.json()

const response = await fetch(
  "https://api.trellis.sh/v1/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  { headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
const chat = await response.json();

{
  "id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  "agent_id": "4f531a2a-22c0-4104-a9bf-4c97f29a2e23",
  "title": "Revenue Analysis",
  "preview": "Show me monthly revenue trends",
  "created_at": "2026-08-08T18:00:00+00:00",
  "updated_at": "2026-08-08T18:00:03+00:00",
  "is_processing": true,
  "running_turn_id": "26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b",
  "running_turn_last_seq": 7,
  "active_turn": {
    "turn_id": "26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b",
    "chat_id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
    "status": "in_progress",
    "created_at": "2026-08-08T18:00:01+00:00",
    "completed_at": null,
    "last_seq": 7,
    "partial_content": "Revenue increased by",
    "result_message_id": null,
    "alive": true,
    "replay_available": true,
    "replay_degraded": false,
    "error": null
  },
  "scoped_project_ids": [],
  "messages": [
    {
      "id": "b3ebae7f-e265-47e4-92dd-344d396f0c33",
      "role": "user",
      "type": "user",
      "content": "Show me monthly revenue trends",
      "timestamp": "2026-08-08T18:00:01+00:00",
      "metadata": null
    }
  ],
  "active_panel": null,
  "panels": []
}

{"detail":"Chat not found"}

Returns the full persisted conversation plus the authoritative recovery snapshot for any running turn. Message type values match the WebSocket event taxonomy; tool payloads are JSON-encoded in each message’s content string.

string

required

Bearer token obtained from Authenticate.

string

required

Member-owned chat UUID.

Chat fields

string

required

Chat UUID.

string | null

required

Agent binding used in WebSocket and REST-turn URLs. Legacy chats can return null; clients must use their organization’s configured published agent UUID, verified against List Agents. Do not infer it from display name or is_trellis_default. An unbound legacy row remains null after use, so resolve the configured fallback each time.

string

required

Display title.

string

Chat preview.

string

required

ISO 8601 creation timestamp.

string

required

ISO 8601 timestamp of latest activity.

string[]

required

Effective project scope persisted on the chat, in first-occurrence request order and limited to at most two IDs. When a request sets scope, the server silently filters invalid, unknown, out-of-organization, non-permitted, duplicate, and excess requested IDs before persisting this list.

Durable-turn recovery fields

boolean

required

Liveness hint for the running turn. A stale running row can return false; do not use this field alone to unlock the composer.

string | null

required

Authoritative signal that the chat owns a running turn. Keep new submissions blocked while this is non-null.

integer

required

Recovery watermark. The returned messages plus active_turn.partial_content represent canonical content through this sequence. Resume strictly after it.

object | null

required

Snapshot of the running turn, or null.

Show Active turn object

string

required

Durable turn UUID.

string

required

Owning chat UUID.

string

required

Public lifecycle status. An active row reports in_progress; the complete status vocabulary is in_progress, completed, failed, and cancelled.

string

required

ISO 8601 acceptance timestamp.

string | null

required

Terminal timestamp; null while running.

integer

required

Same durable watermark represented by running_turn_last_seq.

string | null

required

Authoritative partial assistant text through last_seq.

string | null

required

Persisted final message ID when available; normally null while active.

boolean

required

Whether the producer heartbeat is currently fresh. A false value does not remove the running row.

boolean

required

Replay eligibility hint. The turn-status endpoint probes replay availability exactly, and a later WebSocket resume may still report gap, degraded, or expired.

boolean

required

Whether exact event replay has been permanently degraded for this turn.

object | null

required

Reserved error field; null for an active turn.

Reconcile a broken stream

Use this response as the correctness baseline on cold load and after a disconnected or uncertain stream. Exact WebSocket replay is an optional optimization; clients must support REST reconciliation even when replay usually succeeds.

Replace local rows with messages from this response.
Render active_turn.partial_content as the in-progress assistant answer.
Replace the local cursor with running_turn_last_seq. Do not append an older client buffer to the returned snapshot.
If running_turn_id still matches, keep the composer locked and send WebSocket resume from this watermark. If the socket returns a resume fallback control frame, refetch this endpoint immediately and retry after backoff.
When running_turn_id is null, terminal history is in messages.

See WebSocket resume for the full protocol.

Messages

array

required

Persisted messages in transcript order.

Show Message object

string

required

Message UUID.

string

required

user or assistant.

string

required

user, final, tool_call, tool_result, tool_message, scope_notice, or error.

string

required

Text content. Tool calls/results are JSON-encoded strings with the same structured object carried live by the WebSocket.

string

required

ISO 8601 persistence timestamp.

object | null

required

Message metadata such as feedback and uploads.

Show Common metadata fields

string

positive or negative.

string

Stored negative-feedback context, when present. Positive feedback removes it; a negative update without a non-empty note leaves any previously stored note unchanged.

array

Attached uploads. Each item can include id, filename, upload_type, mime_type, file_size, storage_path, and a freshly generated presigned_url. The URL expires after one hour and can be null if signing fails.

Panels

object | null

required

Current typed panel as {id, type, content, entity_id, entity_version}, or null.

array

required

Lightweight panel rows shaped as {id, type, chat_message_id}. Fetch complete panel content with Get Panel.

curl "https://api.trellis.sh/v1/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests

response = requests.get(
    "https://api.trellis.sh/v1/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
chat = response.json()

const response = await fetch(
  "https://api.trellis.sh/v1/chats/9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  { headers: { Authorization: "Bearer YOUR_TOKEN" } },
);
const chat = await response.json();

{
  "id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  "agent_id": "4f531a2a-22c0-4104-a9bf-4c97f29a2e23",
  "title": "Revenue Analysis",
  "preview": "Show me monthly revenue trends",
  "created_at": "2026-08-08T18:00:00+00:00",
  "updated_at": "2026-08-08T18:00:03+00:00",
  "is_processing": true,
  "running_turn_id": "26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b",
  "running_turn_last_seq": 7,
  "active_turn": {
    "turn_id": "26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b",
    "chat_id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
    "status": "in_progress",
    "created_at": "2026-08-08T18:00:01+00:00",
    "completed_at": null,
    "last_seq": 7,
    "partial_content": "Revenue increased by",
    "result_message_id": null,
    "alive": true,
    "replay_available": true,
    "replay_degraded": false,
    "error": null
  },
  "scoped_project_ids": [],
  "messages": [
    {
      "id": "b3ebae7f-e265-47e4-92dd-344d396f0c33",
      "role": "user",
      "type": "user",
      "content": "Show me monthly revenue trends",
      "timestamp": "2026-08-08T18:00:01+00:00",
      "metadata": null
    }
  ],
  "active_panel": null,
  "panels": []
}

{"detail":"Chat not found"}

Overview

Authentication

Agents

Datasources

Saved Queries

Models

Chats

Artifacts

Jobs

Voice

Audio

User Memories

Organization Rules

Admin

Chat fields

Durable-turn recovery fields

Reconcile a broken stream

Messages

Panels

​Chat fields

​Durable-turn recovery fields

​Reconcile a broken stream

​Messages

​Panels

Chat fields

Durable-turn recovery fields

Reconcile a broken stream

Messages

Panels