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. Specify projectId for a single Project. Sessions must specify organizationId when listing Agents across Projects. Organization-scoped credentials may omit both.
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. |
organizationId | string | optional | Selects the organization for the Agent list. Required for sessions when projectId is omitted. Omit when selecting a single Project. |
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. | 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. |
organizationId | string | optional | Selects the authorization organization for a legacy System Agent. Required for sessions without Project Agent coordinates. Omit when addressing a Project 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. | 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. |
organizationId | string | optional | Selects the authorization organization for a legacy System Agent. Required for sessions without Project Agent coordinates. Omit when addressing a Project 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. | 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. |
organizationId | string | optional | Selects the authorization organization for a legacy System Agent. Required for sessions without Project Agent coordinates. Omit when addressing a Project 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. | 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 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. |
organizationId | string | optional | Selects the authorization organization for a legacy System Agent. Required for sessions without Project Agent coordinates. Omit when addressing a Project 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. | 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. |
organizationId | string | optional | Selects the authorization organization for a legacy System Agent. Required for sessions without Project Agent coordinates. Omit when addressing a Project 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. | 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 resolves the organization from projectId and requires agentId. It does not deploy or activate an Environment. Sessions publishing System Agents must specify organizationId. Organization-scoped credentials may omit it. Delegate edges must reference explicit canonical revision pins. Idempotency-Key applies only to Project Agent publication: retries with the same payload replay the completed response; reusing it with a different payload returns 409. System Agent publication must be keyless; a nonempty Idempotency-Key returns 400. Repeating a keyless System publication converges by content, but does not provide a completed-response receipt or permission for automatic retries.
Parameters
query
| Name | Type | Required | Description |
|---|---|---|---|
organizationId | string | optional | Selects the authorization organization for System Agent publication. Required for sessions publishing System Agents. Omit for Project Agent publication. |
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 — 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. | 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) |