Projects
52 operations.
List projects
GET /api/v1/projects
Parameters
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List projects. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List projects. |
organizationId | string | optional | Organization that owns the Projects. Required for session credentials. A credential scoped to one organization may omit it. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (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) |
Create a project
POST /api/v1/projects
Parameters
query
| Name | Type | Required | Description |
|---|---|---|---|
organizationId | string | optional | Organization that owns the Projects. Required for session credentials. A credential scoped to one organization may omit it. |
Request body
Required — Request body for: Create a project.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | required | |
name | string | required | |
abcdReleaseId | string | optional | |
templateId | string | optional |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — type: "project" (required); id: string (required); organizationId: string (required); slug: string (required); name: string (required); status: "provisioning" | "active" | "paused" | "deleting" (required); operationTimeoutMs: integer; role: "admin" | "developer" | "viewer"; createdAt: string (required); updatedAt: string (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 a project
GET /api/v1/projects/{projectId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get a project. |
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) |
Update a project
PATCH /api/v1/projects/{projectId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update a project. |
Request body
Required — Request body for: Update a project.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
name | string | optional | |
slug | string | optional | |
status | "active" | "paused" | optional | |
operationTimeoutMs | integer | optional | Elapsed time limit in milliseconds for one atomic operation, including SQL and retries. Defaults to 10000; configurable from 1 to 300000. Does not change row, mutation, or statement limits. |
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) |
Request project deletion
DELETE /api/v1/projects/{projectId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Request project deletion. |
Responses
| Status | Description | Body |
|---|---|---|
202 | Response for status 202 | 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 project agents
GET /api/v1/projects/{projectId}/agents
Returns the canonical Agents owned by this Project with cursor pagination.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List project agents. |
query
| Name | Type | Required | Description |
|---|---|---|---|
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List project agents. |
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List project agents. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — agents: array<object> (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) |
Create a project agent
POST /api/v1/projects/{projectId}/agents
Creates a Project Agent identity. Publish an immutable Agent revision separately before selecting it for a Release.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create a project agent. |
Request body
Required — Request body for: Create a project agent.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | required | |
name | string | required | |
description | string | optional |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — type: "agent" (required); id: string (required); slug: string (required); name: string (required); description: string; status: "draft" | "active" | "paused" | "deleting" (required); createdAt: string (required); updatedAt: string (required); scope: "project" (required); projectId: string (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 a project agent
GET /api/v1/projects/{projectId}/agents/{agentId}
Returns one canonical Project Agent identity and its lifecycle status within the requested Project.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get a project agent. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Get a project agent. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "agent" (required); id: string (required); slug: string (required); name: string (required); description: string; status: "draft" | "active" | "paused" | "deleting" (required); createdAt: string (required); updatedAt: string (required); scope: "project" (required); projectId: string (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) |
Update a project agent
PATCH /api/v1/projects/{projectId}/agents/{agentId}
Updates the Project Agent display metadata. Immutable Agent revisions and their content are not changed by this request.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update a project agent. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Update a project agent. |
Request body
Required — Request body for: Update a project agent.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
name | string | optional | |
description | string | null | optional |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "agent" (required); id: string (required); slug: string (required); name: string (required); description: string; status: "draft" | "active" | "paused" | "deleting" (required); createdAt: string (required); updatedAt: string (required); scope: "project" (required); projectId: string (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 a project agent
DELETE /api/v1/projects/{projectId}/agents/{agentId}
Marks the Project Agent as deleting and returns 202 with the canonical resource. New execution admission is disabled; existing immutable revisions, deployments and run history are retained. No prior cancellation of jobs or runs is required.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Delete a project agent. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Delete a project agent. |
Responses
| Status | Description | Body |
|---|---|---|
202 | Response for status 202 | application/json — object — agent: object (required); deleting: true (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 Agent revisions
GET /api/v1/projects/{projectId}/agents/{agentId}/revisions
Lists immutable revisions for the canonical Project Agent. Cursors continue the same Project and Agent scope.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List Agent revisions. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to List Agent revisions. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List Agent revisions. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List Agent revisions. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — revisions: array<object> (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) |
Create an Agent revision
POST /api/v1/projects/{projectId}/agents/{agentId}/revisions
Creates one immutable Agent revision. The returned revision ID is the exact pin accepted by Release creation; it does not silently follow a later revision.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create an Agent revision. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Create an Agent revision. |
Request body
Required — Request body for: Create an Agent revision.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
content | object | required | |
grantedOperations | array<"agents:invoke-operation" | "agents:manage-workflows" | "agents:render-presentation" | "projects:list" | "projects:get" | "projects:create" | "projects:update" | "projects:delete" | "projects:read-runtime-data" | "analytics:read" | "deployments:create" | "activations:create" | "provider-credentials:list" | "provider-credentials:get" | "provider-credentials:create" | "provider-credentials:update" | "provider-credentials:delete" | "provider-credentials:versions:create" | "organizations:create" | "organizations:accept-invitation" | "users:update" | "organizations:get" | "organizations:delete" | "organizations:update" | "organizations:manage-user-groups" | "organizations:manage-members" | "organization-variables:list" | "organization-variables:manage" | "connections:list" | "connections:get" | "connections:create" | "connections:update" | "connections:delete" | "external-integrations:create" | "external-integrations:get" | "external-integrations:invoke" | "api-keys:list" | "api-keys:get" | "api-keys:create" | "api-keys:revoke" | "definitions:list" | "definitions:get" | "definitions:create" | "definitions:update" | "definitions:delete" | "operation-invocations:list" | "operation-approvals:list" | "operation-approvals:approve" | "operation-approvals:reject" | "agents:get" | "agents:list" | "agents:revisions:create" | "agents:revisions:get" | "agents:revisions:list" | "agents:delete" | "agents:push" | "agent-runs:cancel" | "agent-runs:continue" | "agent-runs:create" | "agent-runs:personalize" | "agent-runs:get" | "agent-runs:list" | "agent-runs:read-organization-system-runs" | "agent-runs:stream" | "agent-runs:steps:get" | "agent-runs:steps:list" | "agent-runs:steps:checkpoints:get" | "agent-runs:checkpoints:list" | "agent-jobs:list" | "agent-jobs:get" | "agent-jobs:create" | "agent-jobs:update" | "agent-jobs:delete" | "agent-jobs:run-now" | "webhooks:list" | "webhooks:create" | "webhooks:delete" | "webhooks:rotate-secret" | "webhooks:replay" | "webhooks:retry-dead" | "templates:search" | "templates:read" | "billing:read" | "billing:manage" | "work-memory:read" | "tenants:manage"> | optional |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — type: "agentRevision" (required); id: string (required); agentId: string (required); revisionNumber: integer (required); content: object (required); grantedOperations: array<string> (required); createdBy: string (required); createdAt: string (required); contentDigest: string (required); delegateAgents: array<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 Agent revision
GET /api/v1/projects/{projectId}/agents/{agentId}/revisions/{agentRevisionId}
Returns the exact immutable Agent revision identified by the URL, without resolving the Agent's latest revision or merging another Agent.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get an Agent revision. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Get an Agent revision. |
agentRevisionId | string | required | Identifies the immutable Project Agent revision being addressed. Applies to Get an Agent revision. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "agentRevision" (required); id: string (required); agentId: string (required); revisionNumber: integer (required); content: object (required); grantedOperations: array<string> (required); createdBy: string (required); createdAt: string (required); contentDigest: string (required); delegateAgents: array<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 project environments
GET /api/v1/projects/{projectId}/environments
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List project environments. |
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) |
Create a custom project environment
POST /api/v1/projects/{projectId}/environments
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create a custom project environment. |
Request body
Required — Request body for: Create a custom project environment.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | required | |
abcdReleaseId | string | optional | |
displayName | string | required |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | 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 project environment
GET /api/v1/projects/{projectId}/environments/{environmentId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get project environment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get project environment. |
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) |
Update project environment
PATCH /api/v1/projects/{projectId}/environments/{environmentId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update project environment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Update project environment. |
Request body
Required — Request body for: Update project environment.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
lifecycle | "provisioning" | "active" | "paused" | "deleting" | optional | |
expectedLifecycle | "provisioning" | "active" | "paused" | "deleting" | optional | |
slug | string | optional | |
displayName | string | optional |
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 custom project environment
DELETE /api/v1/projects/{projectId}/environments/{environmentId}
Marks a custom Project Environment for deletion and queues exact owned runtime cleanup. Built-in development, preview, and production Environments are protected and return 409. The response is an asynchronous deletion receipt; it does not claim that provider cleanup has already finished.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Delete custom project environment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Delete custom project environment. |
Responses
| Status | Description | Body |
|---|---|---|
202 | Response for status 202 | 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 active deployment
GET /api/v1/projects/{projectId}/environments/{environmentId}/activation
Returns the current active Deployment coordinate for this Environment, including its Release and configuration revision. A valid Environment with no active Deployment returns 404; no provider or runtime locator is exposed.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get active deployment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get active deployment. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — activationId: string (required); deploymentId: string (required); generation: integer (required); environmentId: string (required); projectId: string (required); releaseId: string | null (required); configurationRevisionId: string (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 activation history
GET /api/v1/projects/{projectId}/environments/{environmentId}/activations
Lists immutable activation records for one exact Project Environment. Use pagination.nextCursor for the next page; the cursor is opaque and bound to this Project/Environment. A missing or inaccessible coordinate is 404, and malformed pagination is 422.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List activation history. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to List activation history. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List activation history. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List activation history. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — activations: array<object> (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) |
Activate deployment
POST /api/v1/projects/{projectId}/environments/{environmentId}/activations
Synchronously activates an eligible ready Deployment and atomically advances this Environment's active pointer and generation. The expectedGeneration field is a compare-and-set guard; non-ready or stale/conflicting requests return 409, an activation that cannot take the runtime cutover lock before running operations finish returns 409 with details.conflictReason runtime_cutover_busy and details.retryable true, while a missing or foreign Project/Environment/Deployment coordinate returns 404.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Activate deployment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Activate deployment. |
Request body
Required — Request body for: Activate deployment.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
deploymentId | string | required | |
expectedGeneration | integer | required |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — activationId: string (required); deploymentId: string (required); generation: integer (required); environmentId: string (required); projectId: string (required); releaseId: string | null (required); configurationRevisionId: string (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 activation
GET /api/v1/projects/{projectId}/environments/{environmentId}/activations/{activationId}
Returns one immutable Activation for the exact Project Environment coordinate. The response includes the pinned Deployment, Release, configuration revision, generation, actor, and timestamps; an unknown or foreign activation is 404.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get an activation. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get an activation. |
activationId | string | required | Identifies the Project Environment activation being addressed. Applies to Get an activation. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — activationId: string (required); deploymentId: string (required); generation: integer (required); environmentId: string (required); projectId: string (required); releaseId: string | null (required); configurationRevisionId: string (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 Environment Agents
GET /api/v1/projects/{projectId}/environments/{environmentId}/agents
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List Environment Agents. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to List Environment Agents. |
query
| Name | Type | Required | Description |
|---|---|---|---|
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List Environment Agents. |
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List Environment Agents. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — agents: array<object> (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) |
Create an Environment Agent
POST /api/v1/projects/{projectId}/environments/{environmentId}/agents
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create an Environment Agent. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Create an Environment Agent. |
Request body
Required — Request body for: Create an Environment Agent.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | required | |
name | string | required | |
description | string | optional |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — type: "agent" (required); id: string (required); slug: string (required); name: string (required); description: string; status: "draft" | "active" | "paused" | "deleting" (required); createdAt: string (required); updatedAt: string (required); scope: "project" (required); projectId: string (required); organizationId: string (required); environmentId: string (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 Environment Agent
GET /api/v1/projects/{projectId}/environments/{environmentId}/agents/{agentId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get an Environment Agent. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get an Environment Agent. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Get an Environment Agent. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "agent" (required); id: string (required); slug: string (required); name: string (required); description: string; status: "draft" | "active" | "paused" | "deleting" (required); createdAt: string (required); updatedAt: string (required); scope: "project" (required); projectId: string (required); organizationId: string (required); environmentId: string (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) |
Update Environment Agent metadata
PATCH /api/v1/projects/{projectId}/environments/{environmentId}/agents/{agentId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update Environment Agent metadata. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Update Environment Agent metadata. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Update Environment Agent metadata. |
Request body
Required — Request body for: Update Environment Agent metadata.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
name | string | optional | |
description | string | null | optional |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "agent" (required); id: string (required); slug: string (required); name: string (required); description: string; status: "draft" | "active" | "paused" | "deleting" (required); createdAt: string (required); updatedAt: string (required); scope: "project" (required); projectId: string (required); organizationId: string (required); environmentId: string (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 Environment Agent
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/agents/{agentId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Delete an Environment Agent. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Delete an Environment Agent. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Delete an Environment Agent. |
Responses
| Status | Description | Body |
|---|---|---|
202 | Response for status 202 | application/json — object — agent: object (required); deleting: true (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) |
Read allowed models configured for the active Agent deployment
GET /api/v1/projects/{projectId}/environments/{environmentId}/agents/{agentId}/available-models
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Read allowed models configured for the active Agent deployment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Read allowed models configured for the active Agent deployment. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Read allowed models configured for the active Agent deployment. |
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 Environment Agent revisions
GET /api/v1/projects/{projectId}/environments/{environmentId}/agents/{agentId}/revisions
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List Environment Agent revisions. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to List Environment Agent revisions. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to List Environment Agent revisions. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List Environment Agent revisions. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List Environment Agent revisions. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — revisions: array<object> (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) |
Create an Environment Agent revision
POST /api/v1/projects/{projectId}/environments/{environmentId}/agents/{agentId}/revisions
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create an Environment Agent revision. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Create an Environment Agent revision. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Create an Environment Agent revision. |
Request body
Required — Request body for: Create an Environment Agent revision.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
content | object | required | |
grantedOperations | array<"agents:invoke-operation" | "agents:manage-workflows" | "agents:render-presentation" | "projects:list" | "projects:get" | "projects:create" | "projects:update" | "projects:delete" | "projects:read-runtime-data" | "analytics:read" | "deployments:create" | "activations:create" | "provider-credentials:list" | "provider-credentials:get" | "provider-credentials:create" | "provider-credentials:update" | "provider-credentials:delete" | "provider-credentials:versions:create" | "organizations:create" | "organizations:accept-invitation" | "users:update" | "organizations:get" | "organizations:delete" | "organizations:update" | "organizations:manage-user-groups" | "organizations:manage-members" | "organization-variables:list" | "organization-variables:manage" | "connections:list" | "connections:get" | "connections:create" | "connections:update" | "connections:delete" | "external-integrations:create" | "external-integrations:get" | "external-integrations:invoke" | "api-keys:list" | "api-keys:get" | "api-keys:create" | "api-keys:revoke" | "definitions:list" | "definitions:get" | "definitions:create" | "definitions:update" | "definitions:delete" | "operation-invocations:list" | "operation-approvals:list" | "operation-approvals:approve" | "operation-approvals:reject" | "agents:get" | "agents:list" | "agents:revisions:create" | "agents:revisions:get" | "agents:revisions:list" | "agents:delete" | "agents:push" | "agent-runs:cancel" | "agent-runs:continue" | "agent-runs:create" | "agent-runs:personalize" | "agent-runs:get" | "agent-runs:list" | "agent-runs:read-organization-system-runs" | "agent-runs:stream" | "agent-runs:steps:get" | "agent-runs:steps:list" | "agent-runs:steps:checkpoints:get" | "agent-runs:checkpoints:list" | "agent-jobs:list" | "agent-jobs:get" | "agent-jobs:create" | "agent-jobs:update" | "agent-jobs:delete" | "agent-jobs:run-now" | "webhooks:list" | "webhooks:create" | "webhooks:delete" | "webhooks:rotate-secret" | "webhooks:replay" | "webhooks:retry-dead" | "templates:search" | "templates:read" | "billing:read" | "billing:manage" | "work-memory:read" | "tenants:manage"> | optional |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — type: "agentRevision" (required); id: string (required); agentId: string (required); revisionNumber: integer (required); content: object (required); grantedOperations: array<string> (required); createdBy: string (required); createdAt: string (required); contentDigest: string (required); delegateAgents: array<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 Environment Agent revision
GET /api/v1/projects/{projectId}/environments/{environmentId}/agents/{agentId}/revisions/{agentRevisionId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get an Environment Agent revision. |
agentId | string | required | Identifies the Project Agent being addressed. Applies to Get an Environment Agent revision. |
agentRevisionId | string | required | Identifies the immutable Project Agent revision being addressed. Applies to Get an Environment Agent revision. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get an Environment Agent revision. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "agentRevision" (required); id: string (required); agentId: string (required); revisionNumber: integer (required); content: object (required); grantedOperations: array<string> (required); createdBy: string (required); createdAt: string (required); contentDigest: string (required); delegateAgents: array<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 deployments
GET /api/v1/projects/{projectId}/environments/{environmentId}/deployments
Lists Deployments belonging to the exact Project Environment coordinate. Deployment execution state is reported by the returned lifecycle status.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List deployments. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to List deployments. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List deployments. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List deployments. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — deployments: array<object> (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) |
Create a deployment
POST /api/v1/projects/{projectId}/environments/{environmentId}/deployments
Validates the Release's artifacts, then atomically claims the Idempotency-Key and queues the Deployment for asynchronous execution. A replay with the same key and payload returns the original Deployment regardless of later activations. 404: missing Project, Environment, Release, or configuration pins. 409: expected-active-deployment-mismatch, idempotency_key_reused, or an invalid Release snapshot. 422: artifact diagnostics. 503: the execution could not be queued (Retry-After).
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create a deployment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Create a deployment. |
header
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | required |
Request body
Required — Submit an existing Release and explicit Environment configuration revision for asynchronous Deployment execution. Promotion and rollback are new Deployments of an existing Release; expectedActiveDeploymentId optionally guards them against a concurrent activation change.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
releaseId | string | required | Immutable Release whose exact Agent and Definition revision pins will be deployed. |
configurationRevisionId | string | required | Existing immutable configuration revision head for this Project Environment. |
expectedActiveDeploymentId | string | optional | Compare-and-set guard: the ready Deployment the Environment must currently activate. |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — type: "deployment" (required); id: string (required); projectId: string (required); environmentId: string (required); releaseId: string | null (required); configurationRevisionId: string (required); status: "queued" | "validating" | "provisioning" | "materializing" | "ready" | "failed" | "canceled" (required); diagnostics: object | null (required); createdAt: string (required); updatedAt: string (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 deployment
GET /api/v1/projects/{projectId}/environments/{environmentId}/deployments/{deploymentId}
Returns one Deployment for the exact Project and Environment coordinate, including its immutable Release and configuration revision pins.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get deployment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get deployment. |
deploymentId | string | required | Identifies the Project Deployment being addressed. Applies to Get deployment. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "deployment" (required); id: string (required); projectId: string (required); environmentId: string (required); releaseId: string | null (required); configurationRevisionId: string (required); status: "queued" | "validating" | "provisioning" | "materializing" | "ready" | "failed" | "canceled" (required); diagnostics: object | null (required); createdAt: string (required); updatedAt: string (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) |
Cancel a deployment
PATCH /api/v1/projects/{projectId}/environments/{environmentId}/deployments/{deploymentId}
Requests terminal cancellation with an expected-state CAS. Existing materialized resources are retained for cleanup.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Cancel a deployment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Cancel a deployment. |
deploymentId | string | required | Identifies the Project Deployment being addressed. Applies to Cancel a deployment. |
Request body
Required — Request body for: Cancel a deployment.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
status | "canceled" | required | |
expectedStatus | "queued" | "validating" | "provisioning" | "materializing" | "ready" | "failed" | "canceled" | optional | |
reason | string | required |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — type: "deployment" (required); id: string (required); projectId: string (required); environmentId: string (required); releaseId: string | null (required); configurationRevisionId: string (required); status: "queued" | "validating" | "provisioning" | "materializing" | "ready" | "failed" | "canceled" (required); diagnostics: object | null (required); createdAt: string (required); updatedAt: string (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 immutable Deployment source
GET /api/v1/projects/{projectId}/environments/{environmentId}/deployments/{deploymentId}/source
Returns a bare DeploymentSource JSON object for the exact organization, Project, Environment and Deployment. Complete validated captured source is authoritative; only absent capture reads exact retained Release/revision/configuration pins, never current heads. Current projects:get, all application agents:get and agents:revisions:get, and definitions:get authority are required; insufficient authority denies the entire graph. Historical shared Project source remains readable under its original ownership. Configuration exposes only revision, digest and non-secret catalog refs; System publications expose only references, generation and ordered digests. No compilation, execution or state changes occur. Invalid or partial capture fails closed without Release fallback. The endpoint adds no aggregate source or response size quota; ordinary request deadlines and runtime constraints apply.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get immutable Deployment source. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get immutable Deployment source. |
deploymentId | string | required | Identifies the Project Deployment being addressed. Applies to Get immutable Deployment source. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Bare immutable Deployment source. Complete application source and exact ordered pins; System publications expose references and digests only. No private configuration, catalog bodies, credentials, Program bytes or internal manifest. Current read authority is required for the entire application graph; insufficient authority denies the whole response. | application/json — object — projectId: string (required); environmentId: string (required); deploymentId: string (required); releaseId: string | null (required); abcdReleaseId: string | null (required); manifestDigest: string (required); applicationAgents: array<object> (required); definitions: array<object> (required); delegates: array<object> (required); systemDependencies: array<object> (required); systemPublications: array<object> (required); configuration: object (required); compiler: 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) |
Invoke an operation
POST /api/v1/projects/{projectId}/environments/{environmentId}/operations/{definitionIdOrName}/invocations
Execute an operation from the selected deployment. Saturated Environment or API-process invocation capacity returns 429 or 503 with Retry-After before runtime execution begins. Definition data constraint failures return 422 with details.invocationId and a safe details.diagnostic. Inspect persisted diagnostics through the operation invocation list. A required auto-managed field must be included in the deployed domain's auto declarations; it must not be supplied manually. Infrastructure failures remain server errors, not input validation errors. An invocation that waited behind a runtime cutover returns 409 with details.retryable true and details.conflictReason runtime_cutover_busy and writes nothing. An invocation that fails the runtime generation fence because the Environment was activated or moved is retried once against the refreshed Environment pointer; a second fence failure returns 409 with details.retryable true and details.conflictReason runtime_generation_changed and writes nothing. A requestKey replay of a Command already committed under an earlier Deployment returns the stored result; a requestKey reused for a different intent returns 409 with details.conflictReason idempotency_key_reused. A Deployment whose stored definitions no longer compile returns 409 deployment_not_compilable with details.deploymentId and details.diagnosticCodes and writes nothing; push corrected definitions and deploy again.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Invoke an operation. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Invoke an operation. |
definitionIdOrName | one of 2 types | required | Identifies the definition element by its stable identifier or name. Applies to Invoke an operation. |
Request body
Required — Request body for: Invoke an operation.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | required | |
minPosition | string | optional | Queries only: wait up to two seconds for this Environment position. |
params | object | optional | |
actorUserId | string | optional | |
approvalId | string | optional | |
requestKey | string | optional |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — one of 2 types |
202 | Response for status 202 | application/json — object — invocationId: string (required); outcome: 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) |
Render a deployed presentation
POST /api/v1/projects/{projectId}/environments/{environmentId}/presentations/{definitionIdOrName}/renders
Render a presentation from the deployment the caller executes: the Agent Run's pinned or activation-bound Deployment for a process credential, otherwise the active Deployment. Every :query read runs in one read-only snapshot under the same owner, readable_by, soft-delete and access-policy scoping as a query operation. A read that exceeds the execution budget returns 422 with error.code execution_budget_exceeded and details.dimension, details.limit and details.observed. A render whose runtime storage is temporarily unavailable returns 503 with details.diagnostic.retryable true. A render that fails the runtime generation fence because the Environment was activated or moved is retried once against the refreshed Environment pointer; a second fence failure returns 409 with details.retryable true and details.conflictReason runtime_generation_changed or runtime_cutover_busy. A render is a read with no committed effect, so a client may resend it with the same requestKey; every attempt records its own presentation_render invocation.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Render a deployed presentation. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Render a deployed presentation. |
definitionIdOrName | one of 2 types | required | Identifies the definition element by its stable identifier or name. Applies to Render a deployed presentation. |
Request body
Required — Request body for: Render a deployed presentation.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
agentId | string | required | |
minPosition | string | optional | Opaque Environment change position. A generation change requires a new baseline. |
params | object | optional | |
actorUserId | string | optional | |
requestKey | string | optional |
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 Project members
GET /api/v1/projects/{projectId}/members
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List Project members. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List Project members. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List Project members. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — members: array<object> (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) |
Add a Project member
POST /api/v1/projects/{projectId}/members
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Add a Project member. |
Request body
Required — Request body for: Add a Project member.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
userId | string | required | |
role | "admin" | "developer" | "viewer" | required |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — member: 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) |
Update a Project member role
PATCH /api/v1/projects/{projectId}/members/{userId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update a Project member role. |
userId | string | required | Identifies the user whose membership or grant is being addressed. Applies to Update a Project member role. |
Request body
Required — Request body for: Update a Project member role.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
role | "admin" | "developer" | "viewer" | required |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — member: 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) |
Remove a Project member
DELETE /api/v1/projects/{projectId}/members/{userId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Remove a Project member. |
userId | string | required | Identifies the user whose membership or grant is being addressed. Applies to Remove a Project member. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — removed: true (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) |
Read the Project's allowed models and default
GET /api/v1/projects/{projectId}/model-policy
An unconfigured Project returns policy=null and revision=0. Project Agent execution is refused until an administrator explicitly saves a policy. A saved empty policy revokes all models and is distinct from an unconfigured Project.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Read the Project's allowed models and default. |
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) |
Replace the Project model policy at an expected revision
PUT /api/v1/projects/{projectId}/model-policy
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Replace the Project model policy at an expected revision. |
Request body
Required — Request body for: Replace the Project model policy at an expected revision.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
policy | object | required | |
expectedRevision | integer | required |
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 project releases
GET /api/v1/projects/{projectId}/releases
Lists immutable Releases belonging to the Project. Each Release records the exact Agent and Definition revision pins used to build it.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List project releases. |
query
| Name | Type | Required | Description |
|---|---|---|---|
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List project releases. |
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List project releases. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — releases: array<object> (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) |
Create project release
POST /api/v1/projects/{projectId}/releases
Creates an immutable Release from the explicitly supplied Agent and Definition revision IDs. The server validates the complete pin and delegate graph before accepting the Release.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create project release. |
Request body
Required — Create an immutable Release from explicit Agent and Definition revision pins; the server validates the complete delegate graph.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
agentRevisions | array<object> | required | |
definitionRevisions | array<object> | required |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — id: string (required); projectId: string (required); manifest: 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 project release
GET /api/v1/projects/{projectId}/releases/{releaseId}
Returns one immutable Project Release and its revision-pinned manifest; it does not expose provider locators or internal storage details.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get project release. |
releaseId | string | required | Identifies the immutable Project Release being addressed. Applies to Get project release. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — id: string (required); projectId: string (required); manifest: 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 Project user-group grants
GET /api/v1/projects/{projectId}/user-groups
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List Project user-group grants. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List Project user-group grants. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List Project user-group grants. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — grants: array<object> (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) |
Grant a Project user group access
POST /api/v1/projects/{projectId}/user-groups
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Grant a Project user group access. |
Request body
Required — Request body for: Grant a Project user group access.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
userGroupId | string | required | |
role | "admin" | "developer" | "viewer" | required |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — grant: 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) |
Update a Project user-group grant
PATCH /api/v1/projects/{projectId}/user-groups/{userGroupId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update a Project user-group grant. |
userGroupId | string | required | Identifies the Organization or Project user group being addressed. Applies to Update a Project user-group grant. |
Request body
Required — Request body for: Update a Project user-group grant.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
role | "admin" | "developer" | "viewer" | required |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — grant: 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) |
Remove a Project user-group grant
DELETE /api/v1/projects/{projectId}/user-groups/{userGroupId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Remove a Project user-group grant. |
userGroupId | string | required | Identifies the Organization or Project user group being addressed. Applies to Remove a Project user-group grant. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — removed: true (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 selectable ABCD releases
GET /api/v1/projects/abcd-releases
Parameters
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List selectable ABCD releases. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List selectable ABCD releases. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (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) |