Agents

GET /api/orgs/{org_id}/agents

List Agents

List agents in the organization. Requires membership.

Omit limit to get every agent; total is the full count either way.

Every filter and the sort are applied inside the statement, before LIMIT. So the returned page is a genuine page of the filtered, ordered set, and total is the count of that filtered set — not of the org. A caller must not re-filter or re-sort the page it gets back: doing so over one loaded page is what this signature exists to stop.

Parameters

Name	In	Type	Required	Description
deployed	query	boolean	no	true returns only agents with an active revision, false only those without one. Omit for both. Mirrors has_active_revision on the row.
execution_mode	query	AgentExecutionMode	no	Filter by execution mode. Omit to get every mode.
limit	query	integer	no	Max rows to return (1-100). Omit to return every row.
offset	query	integer	no	Rows to skip — pass the previous response’s next_offset.
org_id	path	string (uuid)	yes
project_id	query	string	no	Filter by project id, or ‘none’ for uncategorized agents.
q	query	string	no	Case-insensitive substring match over agent name, slug and description. Blank or whitespace-only is treated as absent.
sort	query	"display_order" | "name" | "created_at" | "last_activity_at"	no	Sort key. display_order (default) is the org’s manual arrangement. last_activity_at is the agent’s most recent chat activity of all time — never-run agents sort last in both directions. Window-scoped rankings (runs / failures / spend over 24h-30d) are not offered here; GET /agents/activity answers those for every agent, unpaginated.
sort_order	query	"asc" | "desc"	no	Sort direction. Omit for the natural direction of the chosen sort: asc for display_order and name, desc for created_at and last_activity_at.
status	query	AgentStatus	no	Filter by lifecycle status. Omit to get both active and archived.

Responses

Status	Description	Body
200	Successful Response	Page_AgentResponse_
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/agents

Create Agent

Create a new agent in the organization. Requires ADMIN or OWNER role.

Parameters

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

Request body (required)

Field	Type	Required	Description
allowed_knowledge_bases	string[]	no
allowed_tools	string[]	no
always_forward_chat_files	boolean	no
auto_pin_enabled	boolean	no
avatar_seed	string	no
can_manage_integrations	boolean	no
can_remember	boolean	no
can_request_human_input	boolean	no
description	string	no
environment_id	string (uuid)	no
execution_mode	string	no
instruction	string	no
model	string	no
model_mode	string	no	Effort level for an org whose plan selects effort rather than models: ‘trivial’ (Trivial), ‘normal’ (Standard) or ‘high_effort’ (High). The platform decides what each level runs (model + reasoning effort + thinking). No level is plan-gated. Rejected with 422 for an org whose plan has direct model choice, where a level would have no effect — such an org sets model/reasoning_effort instead. Null clears it.
mounted_skills	string[]	no
name	string	yes
outcome_schema	object	no
per_chat_cost_limit_usd	number	no
per_chat_credit_limit	number	no
permissions	object	no
pinned_tools	string[]	no
reasoning_effort	string	no
reply_to_incoming_email	boolean	no
sandbox_enabled	boolean	no
status	string	no
system_prompt	string	no
tags	string[]	no
team_id	string (uuid)	no

Responses

Status	Description	Body
201	Successful Response	AgentResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/agents/{agent_id}

Get Agent

Get agent details. Accepts UUID or slug. Requires membership.

Parameters

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

Responses

Status	Description	Body
200	Successful Response	AgentResponse
422	Validation Error	HTTPValidationError

PATCH /api/orgs/{org_id}/agents/{agent_id}

Update Agent

Update agent settings. Accepts UUID or slug. Instruction edits are routed to the draft revision.

Narrowing allowed_tools also unpins: any pinned_tools entry the new grants no longer admit is dropped, because a pin is scope-unioned into the effective allow-set at run time and would otherwise survive the revocation.

Requires ADMIN or OWNER role.

Parameters

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

Request body (required)

Field	Type	Required	Description
allowed_knowledge_bases	string[]	no
allowed_tools	string[]	no
always_forward_chat_files	boolean	no
auto_pin_enabled	boolean	no
auto_pinned_tools	string[]	no
avatar_seed	string	no
can_manage_integrations	boolean	no
can_remember	boolean	no
can_request_human_input	boolean	no
description	string	no
environment_id	string (uuid)	no
execution_mode	string	no
instruction	string	no
model	string	no
model_mode	string	no	Effort level for an org whose plan selects effort rather than models: ‘trivial’ (Trivial), ‘normal’ (Standard) or ‘high_effort’ (High). The platform decides what each level runs (model + reasoning effort + thinking). No level is plan-gated. Rejected with 422 for an org whose plan has direct model choice, where a level would have no effect — such an org sets model/reasoning_effort instead. Null clears it.
mounted_skills	string[]	no
name	string	no
outcome_schema	object	no
owner_user_id	string (uuid)	no
per_chat_cost_limit_usd	number	no
per_chat_credit_limit	number	no
permissions	object	no
pinned_tools	string[]	no
reasoning_effort	string	no
reply_to_incoming_email	boolean	no
run_as	string	no
sandbox_enabled	boolean	no
settings	object	no
status	string	no
system_prompt	string	no
tags	string[]	no
team_id	string (uuid)	no
tools	object[]	no

Responses

Status	Description	Body
200	Successful Response	AgentResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/agents/{agent_id}

Delete Agent

Soft-delete an agent. Accepts UUID or slug. Requires ADMIN or OWNER role.

Parameters

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

Responses

Status	Description	Body
204	Successful Response
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/agents/{agent_id}/artifacts

Get Agent Artifacts

Get artifacts produced by an agent.

Accepts UUID or slug. Returns artifacts ordered by created_at desc. Requires membership in the organization.

Parameters

Name	In	Type	Required	Description
agent_id	path	string	yes
limit	query	integer	no
offset	query	integer	no
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	AgentArtifactListResponse
422	Validation Error	HTTPValidationError

POST /api/orgs/{org_id}/agents/{agent_id}/deploy

Deploy Agent

Deploy the draft revision: activate it.

Accepts UUID or slug. Requires ADMIN or OWNER role.

Parameters

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

Responses

Status	Description	Body
200	Successful Response	AgentResponse
422	Validation Error	HTTPValidationError

DELETE /api/orgs/{org_id}/agents/{agent_id}/draft

Discard Draft

Discard the draft revision for an agent.

Accepts UUID or slug. Requires ADMIN or OWNER role. Returns 422 if no draft exists.

Parameters

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

Responses

Status	Description	Body
200	Successful Response	AgentResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/agents/{agent_id}/events

Get Agent Events

Get the activity timeline for an agent.

Accepts UUID or slug. Returns events ordered by created_at desc (newest first). Requires membership in the organization.

Parameters

Name	In	Type	Required	Description
agent_id	path	string	yes
limit	query	integer	no	Max events to return
offset	query	integer	no	Pagination offset
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	AgentEventTimelineResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/agents/{agent_id}/revisions

List Revisions

List all revisions for an agent, newest first.

Accepts UUID or slug. Requires membership in the organization.

Parameters

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

Responses

Status	Description	Body
200	Successful Response	AgentRevisionListResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/agents/activity

Get Agents Activity

Current state, sparkline and window totals for every agent in the org.

One entry per agent — including agents that have never run — so a grid can key straight off this without deciding what a missing row meant. The three facts a caller needs to tell “loading” from “never ran” from “quiet lately” are last_activity_at (null = never), ran_in_window, and the totals; see services/agent_activity.py.

Money comes back in one unit, named by spend_unit: a BYO org reads cost_usd, everyone else reads credits.

Deliberately not paginated. It is bounded by the org’s agent count, it backs a page that draws all of them at once, and a paged sparkline would just be N round trips wearing a different hat.

Parameters

Name	In	Type	Required	Description
org_id	path	string (uuid)	yes
window	query	string	no	Window ending now. One of 24h, 7d, 14d, 30d.

Responses

Status	Description	Body
200	Successful Response	AgentsActivityResponse
422	Validation Error	HTTPValidationError

GET /api/orgs/{org_id}/agents/deleted

List Deleted Agents

List soft-deleted agents in the organization. Requires ADMIN or OWNER role.

Parameters

Name	In	Type	Required	Description
limit	query	integer	no	Max rows to return (1-100). Omit to return every row.
offset	query	integer	no	Rows to skip — pass the previous response’s next_offset.
org_id	path	string (uuid)	yes

Responses

Status	Description	Body
200	Successful Response	Page_AgentResponse_
422	Validation Error	HTTPValidationError