Chats
GET /api/orgs/{org_id}/chats
Section titled “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 | |
| 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
Section titled “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}
Section titled “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}
Section titled “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
Section titled “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
Section titled “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
Section titled “PATCH /api/orgs/{org_id}/chats/{chat_id}/tags”Update Chat Tags
Update tags on a work chat.
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 |