Agents

7 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}/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 in pagination.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` — agents: array<one of 2 types> (required); pagination: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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

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` — `object` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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

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` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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

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` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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

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 in pagination.nextCursor; omit it for the first page.
A non-null pagination.nextCursor indicates 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` — revisions: array<AgentRevision> (required); pagination: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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` — `object` — data: object (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)

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
`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
`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` — data: one of 2 types (required)
`400`	The request is malformed or cannot be processed.	`application/json` — `PublicApiError` — error: object (required)
`401`	Authentication failed. The Authorization header is missing, or the credential is invalid or expired.	`application/json` — `PublicApiError` — error: object (required)
`403`	Access denied. The authenticated user does not have permission to perform this action.	`application/json` — `PublicApiError` — error: object (required)
`404`	Resource not found.	`application/json` — `PublicApiError` — error: object (required)
`409`	Request conflicts with current state of the resource, including safe deployment conflict classifications.	`application/json` — `PublicApiError` — error: object (required)
`422`	Request validation failed. Check the request body, query parameters, or path parameters.	`application/json` — `PublicApiError` — error: object (required)
`429`	Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying.	`application/json` — `PublicApiError` — error: object (required)
`500`	The server could not complete the request.	`application/json` — `PublicApiError` — error: object (required)
`503`	Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.	`application/json` — `PublicApiError` — error: object (required)