Skip to content
CantoraAPI documentation
POST
/v1/organizations/{organizationId}/projects/{projectId}/environments/{environmentId}/agents/{agentPrincipalId}/releases

Activate an immutable Agent Version for new work

Conditionally append or reuse an Agent Release using the current release ETag. Live activation also requires the exact Test Release for the selected Version.

Authentication

Send an API key as a Bearer token in the Authorization header.

Parameters

NameLocationRequiredDescription
organizationIdpathYes
The Organization to address.
stringA Cantora Organization identifier, prefixed with `org_`.
  • maximum length 64
  • pattern ^org_[\s\S]+$
projectIdpathYes
The Project to address.
stringA Cantora Project identifier, prefixed with `proj_`.
  • maximum length 64
  • pattern ^proj_[\s\S]+$
environmentIdpathYes
The Environment to address.
stringA Cantora Environment identifier, prefixed with `env_`.
  • maximum length 64
  • pattern ^env_[\s\S]+$
agentPrincipalIdpathYes
The Environment Agent Principal to address.
stringA Cantora Principal identifier, prefixed with `principal_`.
  • maximum length 64
  • pattern ^principal_[\s\S]+$
if-matchheaderYes
The current strong resource ETag, including its double quotes.
stringThe current strong Agent Release ETag, including its double quotes.
  • maximum length 12
  • pattern ^"(?:0|[1-9][0-9]{0,9})"$

Request body

Required.

application/json
object
  • unknown properties allowed false
agentVersionIdrequired
stringThe immutable Agent Version to activate.
  • maximum length 64
  • pattern ^agent_version_[\s\S]+$
sourceTestAgentReleaseId
The exact Test Release proving this Version was activated in Test; required for Live only.
Any of
stringA Cantora Agent Release identifier, prefixed with `agent_release_`.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
null
reasonrequired
stringWhy this Agent Version is being activated or restored.
  • maximum length 500
  • minimum length 1
Activate the Agent Version in Test
{
  "agentVersionId": "agent_version_00000000000000000000000000000001",
  "reason": "Activate the first tested support Agent Version."
}

Responses

200ActivatedAgentRelease
application/json
ActivatedAgentReleaseEncoded
Agent Release activated
{
  "outcome": "created",
  "release": {
    "agentReleaseId": "agent_release_00000000000000000000000000000001",
    "organizationId": "org_00000000000000000000000000000002",
    "projectId": "proj_00000000000000000000000000000001",
    "environmentId": "env_00000000000000000000000000000001",
    "agentPrincipalId": "principal_00000000000000000000000000000003",
    "agentDefinitionId": "agentdef_00000000000000000000000000000001",
    "agentVersionId": "agent_version_00000000000000000000000000000001",
    "sourceTestAgentReleaseId": null,
    "precedingAgentReleaseId": null,
    "generation": 1,
    "releaseEtag": "\"1\"",
    "reason": "Activate the first tested support Agent Version.",
    "createdByPrincipalId": "principal_00000000000000000000000000000002",
    "createdAt": "2026-01-15T18:30:00.000Z"
  }
}
400The request path, headers, query, or JSON body did not satisfy the published schema
401Unauthorized
application/json
UnauthorizedEncoded
403Forbidden
application/json
ForbiddenEncoded
404NotFound
application/json
NotFoundEncoded
409Conflict
application/json
ConflictEncoded
412PreconditionFailed
application/json
PreconditionFailedEncoded

Reusable schemas

ActivatedAgentReleaseEncoded

object
  • unknown properties allowed false
outcomerequired
stringWhether this activation created a new Agent Release or reused the current one.
  • allowed values "created", "reused"
releaserequired
AgentReleaseEncodedThe Agent Release selected by the activation.

UnauthorizedEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "Unauthorized"
reasonrequired
stringA safe explanation of why the credential was rejected.

ForbiddenEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "Forbidden"
permissionrequired
stringThe permission required by the refused operation.

NotFoundEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "NotFound"
resourcerequired
stringThe resource type relevant to the error.
idrequired
stringThe identifier supplied for the resource that was not found.

ConflictEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "Conflict"
resourcerequired
stringThe resource type relevant to the error.
reasonrequired
stringA safe explanation of the state conflict.

PreconditionFailedEncoded

object
  • unknown properties allowed false
_tagrequired
stringThe stable machine-readable error type.
  • allowed values "PreconditionFailed"
resourcerequired
stringThe resource type relevant to the error.
  • allowed values "agent", "agentDefinition", "agentConfiguration"
currentAgentReleaseIdrequired
The current Agent Release identifier, or null before the first activation.
Any of
stringA Cantora Agent Release identifier, prefixed with `agent_release_`.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
null
currentEtagrequired
stringThe current strong ETag required for the next conditional activation.
  • maximum length 12
  • pattern ^"(?:0|[1-9][0-9]{0,9})"$

AgentReleaseEncoded

object
  • unknown properties allowed false
agentReleaseIdrequired
stringThe immutable Agent Release identifier.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
organizationIdrequired
stringThe Organization identifier.
  • maximum length 64
  • pattern ^org_[\s\S]+$
projectIdrequired
stringThe Project identifier.
  • maximum length 64
  • pattern ^proj_[\s\S]+$
environmentIdrequired
stringThe Environment identifier.
  • maximum length 64
  • pattern ^env_[\s\S]+$
agentPrincipalIdrequired
stringThe Environment Agent Principal identifier.
  • maximum length 64
  • pattern ^principal_[\s\S]+$
agentDefinitionIdrequired
stringThe Agent Definition identifier.
  • maximum length 64
  • pattern ^agentdef_[\s\S]+$
agentVersionIdrequired
stringThe immutable Agent Version identifier.
  • maximum length 64
  • pattern ^agent_version_[\s\S]+$
sourceTestAgentReleaseIdrequired
The exact Test Release proving Live promotion, or null for a Test Release.
Any of
stringA Cantora Agent Release identifier, prefixed with `agent_release_`.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
null
precedingAgentReleaseIdrequired
The preceding Agent Release identifier, or null for the first activation.
Any of
stringA Cantora Agent Release identifier, prefixed with `agent_release_`.
  • maximum length 64
  • pattern ^agent_release_[\s\S]+$
null
generationrequired
integerThe monotonically increasing Agent Release generation.
  • greater than 0
releaseEtagrequired
stringThe strong ETag for the Agent's current release generation.
  • maximum length 12
  • pattern ^"(?:0|[1-9][0-9]{0,9})"$
reasonrequired
stringThe human-readable reason supplied for the activation or rollback.
createdByPrincipalIdrequired
stringThe Principal that created this immutable record.
  • maximum length 64
  • pattern ^principal_[\s\S]+$
createdAtrequired
stringWhen the resource was created, in UTC.
  • format date-time