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.

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
project_id	query	string	no	Filter by project id, or ‘none’ for uncategorized agents.

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_tools	string[]	no
avatar_seed	string	no
description	string	no
execution_mode	string	no
instruction	string	no
model	string	no
mounted_skills	string[]	no
name	string	yes
per_chat_cost_limit_usd	number	no
permissions	object	no
pinned_tools	string[]	no
provider	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.

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_tools	string[]	no
avatar_seed	string	no
description	string	no
execution_mode	string	no
instruction	string	no
model	string	no
mounted_skills	string[]	no
name	string	no
per_chat_cost_limit_usd	number	no
permissions	object	no
pinned_tools	string[]	no
provider	string	no
reasoning_effort	string	no
reply_to_incoming_email	boolean	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

POST /api/orgs/{org_id}/agents/{agent_id}/regenerate-inbox-token

Regenerate Inbox Token

Regenerate the inbox token for an agent, invalidating the old webhook URL and future email address.

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	RegenerateInboxTokenResponse
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/{agent_id}/tokens

List Agent Tokens

List all non-revoked tokens for an agent. 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	AgentTokenListResponse
422	Validation Error	HTTPValidationError

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

Create Agent Token

Create a new token for an agent. Accepts UUID or slug. Returns plaintext once. 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
description	string	no
name	string	yes
scope	string	no

Responses

Status	Description	Body
201	Successful Response	CreateAgentTokenResponse
422	Validation Error	HTTPValidationError

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

Revoke Agent Token

Revoke an agent token. 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
token_id	path	string (uuid)	yes

Responses

Status	Description	Body
204	Successful Response
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