Push (create or extend) an agent revision
POST /api/v1/agents/push
Creates one immutable Project Agent revision or publishes one System Agent revision. Project authoring resolves the organization from projectId and requires agentId. It does not deploy or activate an Environment. Sessions publishing System Agents must specify organizationId. Organization-scoped credentials may omit it. Delegate edges must reference explicit canonical revision pins. Idempotency-Key applies only to Project Agent publication: retries with the same payload replay the completed response; reusing it with a different payload returns 409. System Agent publication must be keyless; a nonempty Idempotency-Key returns 400. Repeating a keyless System publication converges by content, but does not provide a completed-response receipt or permission for automatic retries.
Parameters
query
| Name | Type | Required | Description |
|---|---|---|---|
organizationId | string | optional | Selects the authorization organization for System Agent publication. Required for sessions publishing System Agents. Omit for Project Agent publication. |
header
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | optional |
Request body
Required — Request body for: Push (create or extend) an agent revision.
application/json
Alternative 1
| Name | Type | Required | Description |
|---|---|---|---|
scopeKey | string | required | |
createOnly | boolean | optional | |
agentKind | "system" | required | |
agentId | unknown | optional | |
environmentId | unknown | optional | |
projectId | unknown | optional | |
agents | object | required |
Alternative 2
| Name | Type | Required | Description |
|---|---|---|---|
scopeKey | string | required | |
createOnly | boolean | optional | |
agentKind | "project" | required | |
agentId | string | required | |
projectId | string | required | |
agents | object | required |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: one of 2 types (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |