Agents
12 operations.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/agents | List agents |
| GET | /api/v1/agents/{coordinator} | Get agent content |
| DELETE | /api/v1/agents/{coordinator} | Delete an agent |
| GET | /api/v1/agents/{coordinator}/delegates/{delegate} | Get agent content |
| DELETE | /api/v1/agents/{coordinator}/delegates/{delegate} | Delete an agent |
| GET | /api/v1/agents/{coordinator}/delegates/{delegate}/meta | Get agent metadata |
| GET | /api/v1/agents/{coordinator}/delegates/{delegate}/revisions | List all revisions of an agent |
| GET | /api/v1/agents/{coordinator}/delegates/{delegate}/revisions/{revisionId} | Get an immutable agent revision |
| GET | /api/v1/agents/{coordinator}/meta | Get agent metadata |
| GET | /api/v1/agents/{coordinator}/revisions | List all revisions of an agent |
| GET | /api/v1/agents/{coordinator}/revisions/{revisionId} | Get an immutable agent revision |
| POST | /api/v1/agents/push | Push (create or extend) an agent revision |
List agents
GET/api/v1/agents
List agents owned by the authenticated organization.
Query Parameters
filter: Filter by Agent name or slug (partial match, case-insensitive)limit: Maximum results (default 20)cursor: Opaque cursor returned inpagination.nextCursor.
Parameters
query
| Name | Type | Required | Description |
|---|---|---|---|
| filter | string | optional | Filters agents using the server-side agent search expression. Applies to List agents. |
| projectId | string | optional | Filters results to the specified Project. Applies to List agents. |
| limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List agents. |
| cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List agents. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Invalid request parameters. | application/json PublicApiError
|
| 401 | Authentication required. | application/json PublicApiError
|
| 403 | projectId not in accessible Projects. | application/json PublicApiError
|
| 404 | projectId not found in the organization. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Get agent content
GET/api/v1/agents/{coordinator}
Get agent content by canonical key. Public reads use the current published revision; authenticated execution reads use the revision captured when execution started.
Path Format
/api/v1/agents/:coordinator— coordinator agent/api/v1/agents/:coordinator/delegates/:delegate— delegate agent
Access
Project Agent reads require an exact Agent and Environment coordinate in the authenticated organization. System Agent reads resolve the active publication by slug and require no Environment selector.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Get agent content. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Get agent content. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Get agent content. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json getApiV1AgentsByCoordinator
|
| 400 | Invalid coordinator or delegate name format. | application/json PublicApiError
|
| 401 | Authentication required. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent not found. | application/json PublicApiError
|
| 409 | The Agent changed concurrently; resolve its active revision and retry. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Delete an agent
DELETE/api/v1/agents/{coordinator}
Begin deletion of an Agent using its resolved immutable revision as the concurrency coordinate. Dependent-row cleanup is performed separately.
Path Format
/api/v1/agents/:coordinator/api/v1/agents/:coordinator/delegates/:delegate
Requirements
- Project Agents: authorized project member.
- System Agents: service-admin only.
- A 409 is returned if the Agent changed during deletion.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Delete an agent. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Delete an agent. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Delete an agent. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Invalid coordinator or delegate name format. | application/json PublicApiError
|
| 401 | Authentication failed or access denied. | application/json PublicApiError
|
| 403 | The authenticated credential lacks the required Agent operation permission. | application/json PublicApiError
|
| 404 | Agent not found. | application/json PublicApiError
|
| 409 | Agent changed concurrently; resolve its active revision and retry. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Get agent content
GET/api/v1/agents/{coordinator}/delegates/{delegate}
Get agent content by canonical key. Public reads use the current published revision; authenticated execution reads use the revision captured when execution started.
Path Format
/api/v1/agents/:coordinator— coordinator agent/api/v1/agents/:coordinator/delegates/:delegate— delegate agent
Access
Project Agent reads require an exact Agent and Environment coordinate in the authenticated organization. System Agent reads resolve the active publication by slug and require no Environment selector.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Get agent content. |
| delegate | string | required | Identifies the delegate agent by its canonical name. Applies to Get agent content. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Get agent content. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Get agent content. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json getApiV1AgentsByCoordinatorDelegatesByDelegate
|
| 400 | Invalid coordinator or delegate name format. | application/json PublicApiError
|
| 401 | Authentication required. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent not found. | application/json PublicApiError
|
| 409 | The Agent changed concurrently; resolve its active revision and retry. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Delete an agent
DELETE/api/v1/agents/{coordinator}/delegates/{delegate}
Begin deletion of an Agent using its resolved immutable revision as the concurrency coordinate. Dependent-row cleanup is performed separately.
Path Format
/api/v1/agents/:coordinator/api/v1/agents/:coordinator/delegates/:delegate
Requirements
- Project Agents: authorized project member.
- System Agents: service-admin only.
- A 409 is returned if the Agent changed during deletion.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Delete an agent. |
| delegate | string | required | Identifies the delegate agent by its canonical name. Applies to Delete an agent. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Delete an agent. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Delete an agent. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Invalid coordinator or delegate name format. | application/json PublicApiError
|
| 401 | Authentication failed or access denied. | application/json PublicApiError
|
| 403 | The authenticated credential lacks the required Agent operation permission. | application/json PublicApiError
|
| 404 | Agent not found. | application/json PublicApiError
|
| 409 | Agent changed concurrently; resolve its active revision and retry. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Get agent metadata
GET/api/v1/agents/{coordinator}/delegates/{delegate}/meta
Get agent owner and revision metadata (owner-only). Public reads use the current published revision; authenticated execution reads use the revision captured when execution started.
Path Format
/api/v1/agents/:coordinator/meta/api/v1/agents/:coordinator/delegates/:delegate/meta
Access
Owner-only: the agent owner must belong to the authenticated organization.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Get agent metadata. |
| delegate | string | required | Identifies the delegate agent by its canonical name. Applies to Get agent metadata. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Get agent metadata. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Get agent metadata. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Invalid coordinator or delegate name. | application/json PublicApiError
|
| 401 | Authentication failed. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent not found or has no revision. | application/json PublicApiError
|
| 409 | The agent changed concurrently; retry the request. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
List all revisions of an agent
GET/api/v1/agents/{coordinator}/delegates/{delegate}/revisions
Retrieve all revisions of an agent (owner-only).
Path Format
/api/v1/agents/:coordinator/revisions/api/v1/agents/:coordinator/delegates/:delegate/revisions
Access
Owner-only: the agent owner must belong to the authenticated organization.
Pagination
limit: Number of revisions to return (1-100, default 20).cursor: Opaque cursor returned inpagination.nextCursor; omit it for the first page.- A non-null
pagination.nextCursorindicates another page is available.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to List all revisions of an agent. |
| delegate | string | required | Identifies the delegate agent by its canonical name. Applies to List all revisions of an agent. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to List all revisions of an agent. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to List all revisions of an agent. |
| limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List all revisions of an agent. |
| cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List all revisions of an agent. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Invalid coordinator or delegate name format. | application/json PublicApiError
|
| 401 | Authentication required. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent not found. | application/json PublicApiError
|
| 409 | The agent changed concurrently; retry the request. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Get an immutable agent revision
GET/api/v1/agents/{coordinator}/delegates/{delegate}/revisions/{revisionId}
Get the exact authenticated owner revision identified by the URL. This endpoint does not resolve the owner's latest revision and does not merge delegate revisions.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Get an immutable agent revision. |
| delegate | string | required | Identifies the delegate agent by its canonical name. Applies to Get an immutable agent revision. |
| revisionId | string | required | Identifies the immutable agent revision being addressed. Applies to Get an immutable agent revision. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Get an immutable agent revision. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Get an immutable agent revision. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json getApiV1AgentsByCoordinatorDelegatesByDelegateRevisionsByRevisionId
|
| 400 | Invalid coordinator, delegate, or revision ID format. | application/json PublicApiError
|
| 401 | Authentication required. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent revision not found. | application/json PublicApiError
|
| 409 | The agent changed concurrently; retry the request. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Get agent metadata
GET/api/v1/agents/{coordinator}/meta
Get agent owner and revision metadata (owner-only). Public reads use the current published revision; authenticated execution reads use the revision captured when execution started.
Path Format
/api/v1/agents/:coordinator/meta/api/v1/agents/:coordinator/delegates/:delegate/meta
Access
Owner-only: the agent owner must belong to the authenticated organization.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Get agent metadata. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Get agent metadata. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Get agent metadata. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Invalid coordinator or delegate name. | application/json PublicApiError
|
| 401 | Authentication failed. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent not found or has no revision. | application/json PublicApiError
|
| 409 | The agent changed concurrently; retry the request. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
List all revisions of an agent
GET/api/v1/agents/{coordinator}/revisions
Retrieve all revisions of an agent (owner-only).
Path Format
/api/v1/agents/:coordinator/revisions/api/v1/agents/:coordinator/delegates/:delegate/revisions
Access
Owner-only: the agent owner must belong to the authenticated organization.
Pagination
limit: Number of revisions to return (1-100, default 20).cursor: Opaque cursor returned inpagination.nextCursor; omit it for the first page.- A non-null
pagination.nextCursorindicates another page is available.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to List all revisions of an agent. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to List all revisions of an agent. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to List all revisions of an agent. |
| limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List all revisions of an agent. |
| cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List all revisions of an agent. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Invalid coordinator or delegate name format. | application/json PublicApiError
|
| 401 | Authentication required. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent not found. | application/json PublicApiError
|
| 409 | The agent changed concurrently; retry the request. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Get an immutable agent revision
GET/api/v1/agents/{coordinator}/revisions/{revisionId}
Get the exact authenticated owner revision identified by the URL. This endpoint does not resolve the owner's latest revision and does not merge delegate revisions.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
| coordinator | string | required | Identifies the coordinator agent by its canonical name. Applies to Get an immutable agent revision. |
| revisionId | string | required | Identifies the immutable agent revision being addressed. Applies to Get an immutable agent revision. |
query
| Name | Type | Required | Description |
|---|---|---|---|
| agentId | string | optional | Selects the Project Agent by its stable identifier. Applies to Get an immutable agent revision. |
| environmentId | string | optional | Selects the active Project environment coordinate. Applies to Get an immutable agent revision. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json getApiV1AgentsByCoordinatorRevisionsByRevisionId
|
| 400 | Invalid coordinator, delegate, or revision ID format. | application/json PublicApiError
|
| 401 | Authentication required. | application/json PublicApiError
|
| 403 | Access denied. The authenticated user does not have permission to perform this action. | application/json PublicApiError
|
| 404 | Agent revision not found. | application/json PublicApiError
|
| 409 | The agent changed concurrently; retry the request. | application/json PublicApiError
|
| 422 | Request validation failed. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
Push (create or extend) an agent revision
POST/api/v1/agents/push
Creates one immutable Project Agent revision or publishes one System Agent revision. Project authoring requires explicit projectId and agentId coordinates; it does not deploy or activate an Environment. Delegate edges must reference explicit canonical revision pins. When Idempotency-Key is supplied, retries with the same payload replay the completed response; reusing it with a different payload returns 409.
Parameters
header
| Name | Type | Required | Description |
|---|---|---|---|
| Idempotency-Key | string | optional |
Request body
required — Request body for: Push (create or extend) an agent revision.
application/json
Alternative 1
| Name | Type | Required | Description |
|---|---|---|---|
| scopeKey | string | required | |
| createOnly | boolean | optional | |
| agentKind | "system" | required | |
| agentId | unknown | optional | |
| environmentId | unknown | optional | |
| projectId | unknown | optional | |
| agents | object | required |
Alternative 2
| Name | Type | Required | Description |
|---|---|---|---|
| scopeKey | string | required | |
| createOnly | boolean | optional | |
| agentKind | "project" | required | |
| agentId | string | required | |
| projectId | string | required | |
| agents | object | required |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Response for status 200 | application/json object
|
| 400 | Bad Request | application/json PublicApiError
|
| 401 | Authentication failed. Possible reasons: - Authorization header is not provided - Invalid credentials | application/json PublicApiError
|
| 403 | Project Agent is not accessible in this Project. | application/json PublicApiError
|
| 409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json PublicApiError
|
| 422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json PublicApiError
|
| 500 | The server could not complete the request. | application/json PublicApiError
|
| 503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json PublicApiError
|