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

Activate an immutable Agent Version for new Test work

Conditionally append or reuse an Agent Release using the current release ETag, making the selected Version active for new Test work.

Authentication

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

Parameters

NameLocationRequiredDescription
organizationIdpathYes
The Organization to address.
string
All of
  • maximum length 64
A Cantora Organization identifier, prefixed with `org_`.
  • pattern ^org_[\s\S]+$
projectIdpathYes
The Project to address.
string
All of
  • maximum length 64
A Cantora Project identifier, prefixed with `proj_`.
  • pattern ^proj_[\s\S]+$
environmentIdpathYes
The Environment to address.
string
All of
  • maximum length 64
A Cantora Environment identifier, prefixed with `env_`.
  • pattern ^env_[\s\S]+$
agentPrincipalIdpathYes
The Environment Agent Principal to address.
string
All of
  • maximum length 64
A Cantora Principal identifier, prefixed with `principal_`.
  • pattern ^principal_[\s\S]+$
if-matchheaderYes
The current strong resource ETag, including its double quotes.
string
All of
  • maximum length 12
The current strong Agent Release ETag, including its double quotes.
  • 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.
All of
  • maximum length 64
A Cantora Agent Version identifier, prefixed with `agent_version_`.
  • pattern ^agent_version_[\s\S]+$
reasonrequired
stringWhy this Agent Version is being activated or restored.
  • maximum length 500
  • minimum length 1
sourcerequired
AgentVersionSourceThe source revision and automation run that requested this activation.
Activate the Agent Version in Test
{
  "agentVersionId": "agent_version_00000000000000000000000000000001",
  "reason": "Activate the first tested support Agent Version.",
  "source": {
    "repository": "example.invalid/acme/support-agent",
    "commit": "0000000000000000000000000000000000000000",
    "path": "cantora/support-agent.json",
    "workflow": "publish-support-agent",
    "run": "example-1"
  }
}

Responses

200ActivatedAgentRelease
application/json
ActivatedAgentReleaseJsonEncoding
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",
    "precedingAgentReleaseId": null,
    "generation": 1,
    "releaseEtag": "\"1\"",
    "reason": "Activate the first tested support Agent Version.",
    "createdByPrincipalId": "principal_00000000000000000000000000000002",
    "source": {
      "repository": "example.invalid/acme/support-agent",
      "commit": "0000000000000000000000000000000000000000",
      "path": "cantora/support-agent.json",
      "workflow": "publish-support-agent",
      "run": "example-1"
    },
    "createdAt": "2026-01-15T18:30:00.000Z"
  }
}
400The request path, headers, query, or JSON body did not satisfy the published schema
401Unauthorized
application/json
UnauthorizedJsonEncoding
403Forbidden
application/json
ForbiddenJsonEncoding
404NotFound
application/json
NotFoundJsonEncoding
409Conflict
application/json
ConflictJsonEncoding
412PreconditionFailed
application/json
PreconditionFailedJsonEncoding

Reusable schemas

ActivatedAgentReleaseJsonEncoding

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

UnauthorizedJsonEncoding

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.

ForbiddenJsonEncoding

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

NotFoundJsonEncoding

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.

ConflictJsonEncoding

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.

PreconditionFailedJsonEncoding

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
string
All of
  • maximum length 64
A Cantora Agent Release identifier, prefixed with `agent_release_`.
  • pattern ^agent_release_[\s\S]+$
null
currentEtagrequired
stringThe current strong ETag required for the next conditional activation.
All of
  • maximum length 12
The current strong Agent Release ETag, including its double quotes.
  • pattern ^"(?:0|[1-9][0-9]{0,9})"$

AgentVersionSource

object
  • unknown properties allowed false
repositoryrequired
stringThe source repository identifier.
All of
  • minimum length 1
  • maximum length 500
commitrequired
stringThe immutable source revision.
All of
  • minimum length 1
  • maximum length 500
pathrequired
stringThe path within the source repository.
All of
  • minimum length 1
  • maximum length 500
workflowrequired
stringThe source automation workflow identifier.
All of
  • minimum length 1
  • maximum length 500
runrequired
stringThe source automation run identifier.
All of
  • minimum length 1
  • maximum length 500

AgentReleaseJsonEncoding

object
  • unknown properties allowed false
agentReleaseIdrequired
stringThe immutable Agent Release identifier.
All of
  • maximum length 64
A Cantora Agent Release identifier, prefixed with `agent_release_`.
  • pattern ^agent_release_[\s\S]+$
organizationIdrequired
stringThe Organization identifier.
All of
  • maximum length 64
A Cantora Organization identifier, prefixed with `org_`.
  • pattern ^org_[\s\S]+$
projectIdrequired
stringThe Project identifier.
All of
  • maximum length 64
A Cantora Project identifier, prefixed with `proj_`.
  • pattern ^proj_[\s\S]+$
environmentIdrequired
stringThe Environment identifier.
All of
  • maximum length 64
A Cantora Environment identifier, prefixed with `env_`.
  • pattern ^env_[\s\S]+$
agentPrincipalIdrequired
stringThe Environment Agent Principal identifier.
All of
  • maximum length 64
A Cantora Principal identifier, prefixed with `principal_`.
  • pattern ^principal_[\s\S]+$
agentDefinitionIdrequired
stringThe Agent Definition identifier.
All of
  • maximum length 64
A Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • pattern ^agentdef_[\s\S]+$
agentVersionIdrequired
stringThe immutable Agent Version identifier.
All of
  • maximum length 64
A Cantora Agent Version identifier, prefixed with `agent_version_`.
  • pattern ^agent_version_[\s\S]+$
precedingAgentReleaseIdrequired
The preceding Agent Release identifier, or null for the first activation.
Any of
string
All of
  • maximum length 64
A Cantora Agent Release identifier, prefixed with `agent_release_`.
  • pattern ^agent_release_[\s\S]+$
null
generationrequired
integerThe monotonically increasing Agent Release generation.
All of
  • greater than 0
releaseEtagrequired
stringThe strong ETag for the Agent's current release generation.
All of
  • maximum length 12
The current strong Agent Release ETag, including its double quotes.
  • 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.
All of
  • maximum length 64
A Cantora Principal identifier, prefixed with `principal_`.
  • pattern ^principal_[\s\S]+$
sourcerequired
AgentVersionSourceThe source revision and automation provenance.
createdAtrequired
stringWhen the resource was created, in UTC.
  • format date-time