Documentation menu
Agents

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

NameTypeRequiredDescription
organizationIdstringoptionalSelects the authorization organization for System Agent publication. Required for sessions publishing System Agents. Omit for Project Agent publication.

header

NameTypeRequiredDescription
Idempotency-Keystringoptional

Request body

Required — Request body for: Push (create or extend) an agent revision.

application/json

Alternative 1

NameTypeRequiredDescription
scopeKeystringrequired
createOnlybooleanoptional
agentKind"system"required
agentIdunknownoptional
environmentIdunknownoptional
projectIdunknownoptional
agentsobjectrequired

Alternative 2

NameTypeRequiredDescription
scopeKeystringrequired
createOnlybooleanoptional
agentKind"project"required
agentIdstringrequired
projectIdstringrequired
agentsobjectrequired

Responses

StatusDescriptionBody
200Response for status 200application/json — object — data: one of 2 types (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)