Chats

GET /api/orgs/{org_id}/chats

List Work Chats

List work chats with pagination and outcome-based stats.

Stats: throughput = count(SUCCESS outcomes), efficiency = avg cost per SUCCESS outcome.

Parameters

Name	In	Type	Required	Description
agent_id	query	string (uuid)	no
org_id	path	string (uuid)	yes
page	query	integer	no
per_page	query	integer	no
resolution	query	string	no	Filter by how the work came out: success, partial, failed, stopped. This is the filter a needs-a-human queue wants — status=active returns successes, partials and idle chats alike.
since	query	string	no	Time period for stats: 24h, 7d, 30d
sort_by	query	string	no	Sort field: created_at, completed_at, total_cost_usd, title
sort_order	query	string	no	asc or desc
status	query	string	no
tags	query	string[]	no	Filter by tags (ALL must match)

Responses

Status	Description	Body
200	Successful Response	ChatWorkListResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/chats

Create Work Chat

Create a new work chat (manual trigger).

Validates the agent, checks for prompt injection, determines initial ChatStatus based on execution mode, and emits chat.work_created to Hatchet when the chat is ACTIVE.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
agent_id	string (uuid)	yes
description	string	no
tags	string[]	no
title	string	no

Responses

Status	Description	Body
201	Successful Response	ChatWorkResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/chats/{chat_id}

Get Work Chat

Get a single work chat detail.

Parameters

Name	In	Type	Required	Description
chat_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ChatWorkResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/chats/{chat_id}

Delete Work Chat

Soft-delete a work chat.

Parameters

Name	In	Type	Required	Description
chat_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
204	Successful Response
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/chats/{chat_id}/outcomes

List Outcomes

List all outcomes recorded for a chat.

Parameters

Name	In	Type	Required	Description
chat_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	OutcomeListResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/chats/{chat_id}/outcomes

Create Outcome

Record an outcome against a chat (manual / override).

Parameters

Name	In	Type	Required	Description
chat_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
evidence	string	no
goal	string	yes
status	string	no
summary	string	no

Responses

Status	Description	Body
201	Successful Response	OutcomeResponse
422	Validation Error	HTTPValidationError

PATCH /api/orgs/{org_id}/chats/{chat_id}/tags

Update Chat Tags

Update tags on a work chat.

Tag names are also registered in the org’s shared tag registry (idempotent) so they appear in GET /tags and can be renamed/recolored there — see ChatService.rename_tag/remove_tag for how a registry change syncs back into a chat’s tag list.

Parameters

Name	In	Type	Required	Description
chat_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes

Request body (required)

Field	Type	Required	Description
tags	string[]	yes

Responses

Status	Description	Body
200	Successful Response	string[]
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/chats/{chat_id}/trace

Get Chat Trace

Lineage tree for a chat, with the building blocks each chat ran.

The tree is rooted at the topmost ancestor and expanded downward, so the response holds ancestors, siblings and descendants — the card highlights is_current rather than asking for a second request per branch.

Parameters

Name	In	Type	Required	Description
chat_id	path	string (uuid)	yes
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ChatTraceResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/chats/browse

Browse Org Chats

The org-wide All chats table: every agent’s chats in one list.

The same rows, filters, sort and page shape as the per-agent table (/api/orgs/{org_id}/agents/{agent_id}/chats/browse), read at org scope — both go through :func:_chat_list_select and :func:chat_browse_conditions, so a row cannot say one thing here and another there. What differs is the axis each one offers instead of the other’s: this one filters by agent (repeatable), the per-agent one by revision — a revision number only means something inside one agent, so mixing agents makes “v10” a filter that quietly matches unrelated work.

For the same reason revision_version on these rows is only ever a pinned version: resolving an agent’s active revision per row would be one query per agent on the page to fill a column that cannot be compared across them anyway. The org-wide table doesn’t render it.

Visibility is the per-agent table’s, unchanged: private (neutral) chats reach only their creator, and everything is scoped to one org after a membership check.

Parameters

Name	In	Type	Required	Description
agent	query	string (uuid)[]	no	Repeatable agent id filter.
archived	query	boolean	no	True returns archived chats only; false (default) returns active ones.
from	query	string (date-time)	no	Only chats whose last activity is at or after this.
limit	query	integer	no
offset	query	integer	no
order	query	"asc" | "desc"	no
org_id	path	string (uuid)	yes
q	query	string	no	Case-insensitive substring match on the chat title.
resolution	query	string[]	no	Repeatable ChatResolution filter.
sort	query	"activity" | "cost" | "messages"	no
source	query	string[]	no	Repeatable ChatSource filter.
status	query	string[]	no	Repeatable ChatStatus filter.
to	query	string (date-time)	no	Only chats whose last activity is at or before this.

Responses

Status	Description	Body
200	Successful Response	ChatBrowseResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/chats/statuses

List Chat Statuses

Batch status lookup for chats referenced from another surface.

Exists so a view holding N chat ids (a chat transcript’s start_chat tool rows, say) draws N status icons from ONE request instead of N detail fetches — and draws them from the same rollup the conversation sidebar uses, so one chat never shows two different states in one page.

Parameters

Name	In	Type	Required	Description
ids	query	string (uuid)[]	no	Chat ids to look up (max 50)
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	ChatStatusListResponse
422	Validation Error	HTTPValidationError