Projects
51 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. |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Create a project
POST /api/v1/projects
Request body
Required — Request body for: Create a project.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
slug | string | required | |
name | string | required | |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Delete 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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" | "projects:manage-access-grants" | "deployments:create" | "activations:create" | "env:variables:list" | "env:variables:get" | "env:variables:create" | "env:variables:update" | "env:variables:delete" | "provider-credentials:list" | "provider-credentials:get" | "provider-credentials:create" | "provider-credentials:update" | "provider-credentials:delete" | "provider-credentials:versions:create" | "organizations:get" | "organizations:delete" | "organizations:update" | "organizations:manage-user-groups" | "organizations:manage-members" | "organization-integrations:list" | "organization-integrations:get" | "organization-integrations:create" | "organization-integrations:update" | "organization-integrations:delete" | "organization-integrations:verify" | "organization-integrations:presets:list" | "organization-variables:list" | "organization-variables:manage" | "connections:list" | "connections:get" | "connections:create" | "connections:update" | "connections:delete" | "connections:start-oauth" | "api-keys:list" | "api-keys:get" | "api-keys:create" | "api-keys:update" | "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:update" | "agent-runs:steps:create" | "agent-runs:steps:get" | "agent-runs:steps:list" | "agent-runs:steps:checkpoints:create" | "agent-runs:steps:checkpoints:get" | "agent-runs:checkpoints:list" | "agent-runs:attempts:complete" | "agent-runs:attempts:record-usage" | "agent-runs:attempts:heartbeat" | "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" | "webhooks:rebaseline" | "webhooks:events:read" | "templates:search" | "templates:read" | "billing:read" | "billing:manage" | "work-memory:read"> | 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get an 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 | |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Delete 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get 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 (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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 (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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get an 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 (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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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, request-mismatch, 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 (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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get 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 (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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 (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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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 details.issues[0].code execution_budget_exceeded. 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Inspect persisted handoff source binding
GET /api/v1/projects/{projectId}/fda/sources/{agentRunId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Inspect persisted handoff source binding. |
agentRunId | string | required | Identifies the agent run whose state or history is addressed. Applies to Inspect persisted handoff source binding. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get FDA Build availability
GET /api/v1/projects/{projectId}/fda/status
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get FDA Build availability. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Save or resume Project-bound FDA work and handoff
POST /api/v1/projects/{projectId}/fda/works
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Save or resume Project-bound FDA work and handoff. |
Request body
Required — Request body for: Save or resume Project-bound FDA work and handoff.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
requestId | string | required | |
request | string | required | |
sourceRunId | string | optional | |
confirmUnboundSourceProject | boolean | optional | |
notes | object | optional | |
artifacts | array<one of 2 types> | 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Read FDA work with exact artifact state
GET /api/v1/projects/{projectId}/fda/works/{workId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Read FDA work with exact artifact state. |
workId | string | required | Identifies saved FDA work bound to the addressed Project and operating user. Applies to Read FDA work with exact artifact state. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Persist and queue the exact FDA Deployment request for safe resume
POST /api/v1/projects/{projectId}/fda/works/{workId}/deploy
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Persist and queue the exact FDA Deployment request for safe resume. |
workId | string | required | Identifies saved FDA work bound to the addressed Project and operating user. Applies to Persist and queue the exact FDA Deployment request for safe resume. |
Request body
Required — Request body for: Persist and queue the exact FDA Deployment request for safe resume.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
requestId | string | required | |
expectedVersion | integer | required | |
phase | "trial" | "publication" | 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Restore FDA requirement versions, exact candidate evidence and next action
GET /api/v1/projects/{projectId}/fda/works/{workId}/history
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Restore FDA requirement versions, exact candidate evidence and next action. |
workId | string | required | Identifies saved FDA work bound to the addressed Project and operating user. Applies to Restore FDA requirement versions, exact candidate evidence and next action. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Activate the exact approved FDA candidate with live authority and generation checks
POST /api/v1/projects/{projectId}/fda/works/{workId}/publish
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Activate the exact approved FDA candidate with live authority and generation checks. |
workId | string | required | Identifies saved FDA work bound to the addressed Project and operating user. Applies to Activate the exact approved FDA candidate with live authority and generation checks. |
Request body
Required — Request body for: Activate the exact approved FDA candidate with live authority and generation checks.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
expectedVersion | integer | required | |
deploymentId | string | required | |
expectedGeneration | 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Append idempotent FDA work evidence without reusing a different candidate
POST /api/v1/projects/{projectId}/fda/works/{workId}/records
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Append idempotent FDA work evidence without reusing a different candidate. |
workId | string | required | Identifies saved FDA work bound to the addressed Project and operating user. Applies to Append idempotent FDA work evidence without reusing a different candidate. |
Request body
Required — Request body for: Append idempotent FDA work evidence without reusing a different candidate.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
requestId | string | required | |
expectedVersion | integer | required | |
action | one of 10 types | 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List 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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
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. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Read the current FDA run's authoritative work binding
GET /api/v1/projects/fda/context/{agentRunId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
agentRunId | string | required | Identifies the agent run whose state or history is addressed. Applies to Read the current FDA run's authoritative work binding. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |