Appearance
Agents
Read, update, and delete published agents. Agents define the persona, model settings, and alignment behavior for conversations. New agents are created by publishing a draft version. Every agent is either user (a normal Agent Library agent) or tool (a system-seeded, workflow-only agent wrapping a set of connector tools). Tool agents are excluded from GET /agents/chat-agents, the Chat picker, drafts, and eval; they appear only in GET /agents/tool-agents and in workflow run details. Any write to a tool agent returns 403, as does starting a Chat with one. GET /agents/{agent_id} stays readable for any kind.
List agents
GET
/v1/agents
List agent summaries visible to the caller, including the seeded tool agents
and the built-in personas. A tool agent (tagged tool) is readable and browsable
but cannot be chatted with (POST /chats refuses one). The built-in tool agents
are also read-only: they cannot be edited or deleted. They can be copied into a
draft of your own with POST /agent-drafts and source_agent_id.
GET /agents/tool-agents remains the workflow palette's own feed.
Pass mine=true to narrow the list to what the caller created plus the built-ins. Community agents are listed by GET /agents/community.
Each summary carries chat_count, the number of chats bound to the agent that the caller can see.
Pass tags (repeatable) to keep only agents carrying every given tag: tags=tool lists tool agents, including the built-in ones. Pass exclude_tags (repeatable) to leave out agents carrying any given tag. Both combine, and total counts the filtered set. GET /agents/chat-agents lists chat agents only.
Each summary carries connector_providers, the connection providers its tools need, for drawing provider marks without fetching the tool catalog.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
mine
Type
boolean
Default
falsetags
Keep agents that have all of these tags.
exclude_tags
Leave out agents that have any of these tags.
Responses
Successful Response
application/json
JSON "items": [ { "agent_name": "string", "agent_prompt": "string", "anchor_word_candidates": [ "string" ], "can_edit": false, "can_write": false, "chat_count": 0, "chat_model": "string", "color": "string", "connector_providers": [ "string" ], "created_at": "string", "created_by": "string", "created_by_name": "string", "delist_listing_id": "string", "description": "", "enabled_tools": [ "string" ], "has_chats": false, "icon_name": "string", "id": "string", "is_system": false, "listing_source_id": "string", "max_tokens": 0, "org_name": "string", "pinned": false, "ready": false, "source_draft_id": "string", "source_version_id": "string", "tags": [ "string" ], "team_ids": [ "string" ], "temperature": 0, "updated_at": "string", "visibility": "string" } ], "next_cursor": "string", "total": 0
{
}
Samples
List chat agents
GET
/v1/agents/chat-agents
The GET /agents list without tool agents (tagged tool): the agents a Chat can be started with. mine, tags and exclude_tags filter as on GET /agents, and total counts the filtered set.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
mine
Type
boolean
Default
falsetags
Keep agents that have all of these tags.
exclude_tags
Leave out agents that have any of these tags.
Responses
Successful Response
application/json
JSON "items": [ { "agent_name": "string", "agent_prompt": "string", "anchor_word_candidates": [ "string" ], "can_edit": false, "can_write": false, "chat_count": 0, "chat_model": "string", "color": "string", "connector_providers": [ "string" ], "created_at": "string", "created_by": "string", "created_by_name": "string", "delist_listing_id": "string", "description": "", "enabled_tools": [ "string" ], "has_chats": false, "icon_name": "string", "id": "string", "is_system": false, "listing_source_id": "string", "max_tokens": 0, "org_name": "string", "pinned": false, "ready": false, "source_draft_id": "string", "source_version_id": "string", "tags": [ "string" ], "team_ids": [ "string" ], "temperature": 0, "updated_at": "string", "visibility": "string" } ], "next_cursor": "string", "total": 0
{
}
Samples
List community agents
GET
/v1/agents/community
Every org's published agents, unscoped, and nothing else. A community agent is readable and importable but cannot be chatted with, edited or bound into a workflow.
The shelf is paged: follow next_cursor until it is null. tags and exclude_tags filter as on GET /agents.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Query Parameters
cursor
next_cursor from the previous page.
tags
Keep agents that have all of these tags.
exclude_tags
Leave out agents that have any of these tags.
Responses
Successful Response
application/json
JSON "items": [ { "agent_name": "string", "agent_prompt": "string", "anchor_word_candidates": [ "string" ], "can_edit": false, "can_write": false, "chat_count": 0, "chat_model": "string", "color": "string", "connector_providers": [ "string" ], "created_at": "string", "created_by": "string", "created_by_name": "string", "delist_listing_id": "string", "description": "", "enabled_tools": [ "string" ], "has_chats": false, "icon_name": "string", "id": "string", "is_system": false, "listing_source_id": "string", "max_tokens": 0, "org_name": "string", "pinned": false, "ready": false, "source_draft_id": "string", "source_version_id": "string", "tags": [ "string" ], "team_ids": [ "string" ], "temperature": 0, "updated_at": "string", "visibility": "string" } ], "next_cursor": "string", "total": 0
{
}
Samples
List tool agents
GET
/v1/agents/tool-agents
List the tool agents a workflow agent step can use: the built-in tool agents
plus the organization's own tool agents the caller can read. Workflow agent
steps take tool agents only. Not paginated. Built-in tool agents are seeded only
when their provider credentials are configured.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "items": [ { "actions": [ { "connection_key": "string", "description": "string", "id": "string", "name": "string" } ], "built_in": false, "connected": true, "description": "string", "icon_name": "string", "id": "string", "name": "string", "providers": [ "string" ], "slug": "string", "system_prompt": "", "tool_ids": [ "string" ] } ]
{
}
Samples
List the tool catalog
GET
/v1/agents/tools
List the full tool catalog. Each entry carries its connection status and the
per-action grants for the caller's organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "items": [ { "actions": [ { "crudl": "string", "description": "string", "granted": false, "id": "string", "label": "string" } ], "auth_kind": "none", "available": true, "connected": false, "connection_provider": "string", "credential_fields": [ { "key": "string", "label": "string", "secret": false } ], "description": "string", "group": "string", "id": "string", "name": "string", "requires_credentials": true } ]
{
}
Samples
List tool connections
GET
/v1/agents/tools/connections
List the caller organization's connections to tool providers, including which
account each one is linked to and when it was authorized.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Responses
Successful Response
application/json
JSON "is_org_admin": true, "items": [ { "actions": [ { "crudl": "string", "description": "string", "granted": false, "id": "string", "label": "string" } ], "auth_actions": [ "string" ], "auth_mode": "oauth", "category": "integration", "configured": true, "connected": true, "credential_fields": [ { "key": "string", "label": "string", "secret": false } ], "name": "string", "provider": "string", "scope_options": [ { "crudl": "string", "default": true, "description": "string", "label": "string", "scopes": [ "string" ] } ], "tools": [ "string" ] } ]
{
}
Samples
Start provider authorization
GET
/v1/agents/tools/{provider}/authorize
Begin the OAuth authorization flow for a tool provider and return the URL to
send the user to. return_to may be supplied to come back to a specific page;
only same-origin relative paths are accepted.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
provider*
Type
Requiredstring
Query Parameters
return_to
Frontend path to return to after OAuth (e.g. /connections)
scopes
OAuth scopes to request (repeat param for multiple)
Responses
Successful Response
application/json
JSON "authorize_url": "string"
{
}
Samples
Disconnect a provider
DELETE
/v1/agents/tools/{provider}/connection
Remove the organization's connection to a tool provider. Tools from that
provider stop being available to agents and workflows.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
provider*
Type
Requiredstring
Responses
Successful Response
Samples
Connect a provider
POST
/v1/agents/tools/{provider}/connection
Complete a provider connection for credential-based providers, storing the
supplied credentials for the caller's organization.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
provider*
Type
Requiredstring
Request Body
application/json
Org-provided credentials for platform-key tool providers.
API key for single-field platform-key providers (e.g. Google Maps); maps onto the provider's declared credential field.
Any of
Credential fields keyed by the provider's declared credential_fields (multi-field providers, e.g. Jira email/token/site).
Any of
Responses
Successful Response
Samples
Delete an agent
DELETE
/v1/agents/{agent_id}
Delete an agent. Returns 403 when the caller cannot write the agent. That
includes the built-in tool agents, which are system-managed and read-only.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
agent_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
Samples
Get an agent
GET
/v1/agents/{agent_id}
Get full agent details. Readable for any agent kind.
Published agents are immutable — there is no update endpoint. To change any
field (metadata, prompt, model, anchor words, scope), create a draft and
publish a new agent.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
agent_id*
Type
Requiredstring
Format
"uuid"Responses
Successful Response
application/json
JSON "agent_name": "string", "agent_prompt": "string", "anchor_word_candidates": [ "string" ], "can_edit": false, "can_write": false, "chat_count": 0, "chat_model": "string", "color": "string", "connector_providers": [ "string" ], "created_at": "string", "created_by": "string", "created_by_name": "string", "delist_listing_id": "string", "description": "", "enabled_tools": [ "string" ], "has_chats": false, "icon_name": "string", "id": "string", "is_system": false, "listing_source_id": "string", "max_tokens": 0, "org_name": "string", "pinned": false, "ready": false, "source_draft_id": "string", "source_version_id": "string", "tags": [ "string" ], "team_ids": [ "string" ], "temperature": 0, "updated_at": "string", "visibility": "string"
{
}
Samples
List a published agent on the marketplace
POST
/v1/agents/{agent_id}/marketplace
Duplicates this published agent into a new immutable listing readable by every organization on the platform. The original agent is untouched. Re-listing the same agent withdraws your previous listing rather than adding a second. Listing needs no admin rights, but the agent must be one you created.
agentSurface is not accepted — it is derived from the agent's own tags. An agent tagged tool is equipment a workflow step calls; anything else is a chat agent a person talks to.
Returns 400 if the authored text or the agent's own prompt carries a credential, a private network address or an internal hostname — none of which may cross a tenant boundary.
Authorizations
HTTPBearer
Type
HTTP (bearer)
Parameters
Path Parameters
agent_id*
Type
Requiredstring
Format
"uuid"Request Body
application/json
What a publisher may still say about a listing, which is almost nothing.
A listing IS its build: the name, tags and icon are read off the published agent
or workflow rather than accepted here, so the catalog cannot disagree with the
library about what a thing is called. Only the blurb is an override, and only
because a sentence written for strangers is not always the internal one.
Overrides the build's own description. Omit to use that instead.
Any of
Max Length
220Min Length
1Responses
Successful Response
application/json
JSON "listingId": "string", "message": "Listed. Re-listing the same build withdraws the previous listing.", "resourceId": "string", "supersededListingId": "string"
{
}