Agents

All paths below are relative to the base URL https://api.agentdepot.org — for example GET https://api.agentdepot.org/api/orgs/{org_id}/agents. Authenticate with an Authorization: Bearer <token> header. See the REST API reference for details.

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.

The agent’s v1 revision starts as an undeployed draft (has_undeployed_draft: true in the response) — it cannot run a chat until deployed via POST /agents/{id}/deploy. Until then the returned agent fields mirror the v1 draft, so the detail page shows the values just submitted.

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
decision_log_enabled	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), ‘high_effort’ (High) or ‘x_high’ (X-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
tags	string[]	no
team_id	string (uuid)	no
vision_model	string	no	Optional override for the model this agent uses to describe images and scanned pages it opens with read_file (the platform’s “Image and PDF reading” feature model). Null (the default) defers to this org’s own override of that feature, if it has set one, then to the platform’s. Allowed values are the same models this agent could set as model — governed by the same platform/org allowlist chain — narrowed to those whose catalog row supports vision; a model that cannot read images is rejected with 422. Null clears it.

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.

Every behaviour field — instruction, model, reasoning_effort, model_mode, vision_model, allowed_tools, allowed_knowledge_bases, mounted_skills, pinned_tools, outcome_schema, and the capability flags — is routed to the agent’s draft revision (forked from the active one if it has none) and does not take effect until deployed. Pass deploy: true to deploy it in this same request, or call POST /agents/{id}/deploy afterwards; a 409 means the draft would be identical to what is already active. Every other field (name, description, status, execution_mode, team, budgets, tags, …) applies immediately either way.

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
decision_log_enabled	boolean	no
deploy	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), ‘high_effort’ (High) or ‘x_high’ (X-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
tags	string[]	no
team_id	string (uuid)	no
tools	object[]	no
vision_model	string	no	Optional override for the model this agent uses to describe images and scanned pages it opens with read_file (the platform’s “Image and PDF reading” feature model). Null (the default) defers to this org’s own override of that feature, if it has set one, then to the platform’s. Allowed values are the same models this agent could set as model — governed by the same platform/org allowlist chain — narrowed to those whose catalog row supports vision; a model that cannot read images is rejected with 422. Null clears it.

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: seal it, make it active, and mirror its full behavioural config (instruction, model, tools, skills, outcome schema, capability flags — everything PATCH can route to a draft) onto the agent’s live-reading columns.

Accepts UUID or slug. Requires ADMIN or OWNER role. 409 if the draft is identical to the revision already active — sealing it would mint a version nothing distinguishes.

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

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

Create Draft

Start (or reset) the draft from a chosen revision’s full config.

The rollback recipe: the UI’s “Restore as draft” only copies instruction text; this copies the entire behavioural config — model, effort, mode, tools, knowledge bases, mounted skills, pins, outcome schema, every capability flag — from from_version (or, if omitted, from the currently active revision) onto the draft. Follow with POST /agents/{id}/deploy to make it live.

If the agent has no draft, one is created (forking a new version). If it already has a draft, it is overwritten in place (same id/version) — unless it carries unsaved changes of its own, in which case this is refused with a 409 naming how many fields would be discarded; pass replace: true to overwrite anyway. 404 if from_version does not name a live revision on this agent (or, when omitted, if the agent has never been deployed).

Legal while an experiment is running — drafts are always fine to create; only deploying one is refused during a rollout.

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

Request body (required)

Field	Type	Required	Description
from_version	integer	no
replace	boolean	no

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