Skip to content
CantoraAPI documentation
POST
/v1/organizations/{organizationId}/projects/{projectId}/agent-configuration-applies

Apply or recover one complete Agent Configuration

Apply the exact previewed Agent Configuration under optimistic preconditions, or resume the same idempotent request from its durable Configuration Revision.

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]+$

Request body

Required.

application/json
object
  • unknown properties allowed false
requestIdrequired
stringThe idempotency key for this exact apply attempt.
All of
  • minimum length 1
  • maximum length 200
desiredrequired
DesiredAgentConfigurationThe complete desired Test Agent Configuration accepted during preview.
manifestDigestrequired
stringThe lowercase SHA-256 manifest digest returned by preview.
preconditionsrequired
AgentConfigurationPreconditionsThe exact mutable Product State observed during preview.
sourcerequired
AgentConfigurationSourceThe source revision and automation run requesting the apply.

Responses

200ApplyAgentConfigurationResult
application/json
ApplyAgentConfigurationResult
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

ApplyAgentConfigurationResult

object
  • unknown properties allowed false
revisionrequired
ConfigurationRevisionJsonEncodingThe monotonically increasing revision within the Agent Definition.
configurationrequired
AgentConfigurationJsonEncodingThe current Agent Configuration after the apply.

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})"$

DesiredAgentConfiguration

object
  • unknown properties allowed false
intentrequired
stringWhether the configuration creates a new binding or updates an identified Agent Definition.
  • allowed values "create", "update"
agentDefinitionIdrequired
The Agent Definition identifier.
Any of
string
All of
  • maximum length 64
A Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • pattern ^agentdef_[\s\S]+$
null
keyrequired
stringThe stable, human-authored Agent Definition key.
displayNamerequired
stringThe human-readable resource name.
manifestrequired
AgentVersionManifestThe complete immutable Agent behavior and execution-budget declaration.
testReleaserequired
objectThe desired Test Environment and activation reason.
  • unknown properties allowed false
environmentIdrequired
stringThe Environment identifier.
All of
  • maximum length 64
A Cantora Environment identifier, prefixed with `env_`.
  • pattern ^env_[\s\S]+$
reasonrequired
stringThe human-readable reason for activating the Test Agent Version.

AgentConfigurationPreconditions

object
  • unknown properties allowed false
agentDefinitionIdrequired
The Agent Definition identifier.
Any of
string
All of
  • maximum length 64
A Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • pattern ^agentdef_[\s\S]+$
null
definitionKeyrequired
The stable Agent Definition key.
Any of
string
null
definitionDisplayNamerequired
The Agent Definition display name observed during preview, or null when creating it.
Any of
string
null
definitionStatusrequired
The Agent Definition lifecycle status observed during preview, or null when creating it.
Any of
string
  • allowed values "active", "disabled"
null
configurationAuthorityrequired
The one surface allowed to change this Agent Definition and publish its Versions.
Any of
string
  • allowed values "ApiManaged", "DashboardManaged"
null
testAgentPrincipalIdrequired
The Test Agent Principal identifier, or null before it is created.
Any of
string
All of
  • maximum length 64
A Cantora Principal identifier, prefixed with `principal_`.
  • pattern ^principal_[\s\S]+$
null
testReleaseGenerationrequired
integerThe current Test Agent Release generation, starting at zero before activation.
All of
  • minimum 0
currentManifestDigestrequired
The current Test Agent Version manifest digest, or null before the first activation.
Any of
string
null

AgentConfigurationSource

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
actorrequired
stringThe source-control or automation actor that requested the change.
All of
  • minimum length 1
  • maximum length 500

ConfigurationRevisionJsonEncoding

object
  • unknown properties allowed false
configurationRevisionIdrequired
stringThe durable Configuration Revision identifier.
All of
  • maximum length 64
A Cantora Configuration Revision identifier, prefixed with `configuration_revision_`.
  • pattern ^configuration_revision_[\s\S]+$
requestIdrequired
stringThe request identifier used for logs and support.
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]+$
testEnvironmentIdrequired
stringThe Test Environment identifier, or null before it can be resolved.
All of
  • maximum length 64
A Cantora Environment identifier, prefixed with `env_`.
  • pattern ^env_[\s\S]+$
agentDefinitionIdrequired
The Agent Definition identifier.
Any of
string
All of
  • maximum length 64
A Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • pattern ^agentdef_[\s\S]+$
null
testAgentPrincipalIdrequired
The Test Agent Principal identifier, or null before it is created.
Any of
string
All of
  • maximum length 64
A Cantora Principal identifier, prefixed with `principal_`.
  • pattern ^principal_[\s\S]+$
null
agentVersionIdrequired
The immutable Agent Version identifier.
Any of
string
All of
  • maximum length 64
A Cantora Agent Version identifier, prefixed with `agent_version_`.
  • pattern ^agent_version_[\s\S]+$
null
testAgentReleaseIdrequired
The Test Agent Release identifier, or null before it is activated.
Any of
string
All of
  • maximum length 64
A Cantora Agent Release identifier, prefixed with `agent_release_`.
  • pattern ^agent_release_[\s\S]+$
null
manifestDigestrequired
stringThe lowercase SHA-256 digest of the normalized manifest.
statusrequired
stringThe current lifecycle status.
  • allowed values "Pending", "Running", "Succeeded", "Failed"
progressrequired
ConfigurationRevisionProgressHow the Surface presents progress while work runs.
sourcerequired
AgentConfigurationSourceThe source revision and automation provenance.
failurerequired
The safe failure detail, or null unless the Configuration Revision failed.
Any of
ConfigurationRevisionFailureJsonEncoding
null
createdAtrequired
stringWhen the resource was created, in UTC.
  • format date-time
updatedAtrequired
stringWhen the resource was last updated, in UTC.
  • format date-time

AgentConfigurationJsonEncoding

object
  • unknown properties allowed false
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]+$
agentDefinitionIdrequired
stringThe Agent Definition identifier.
All of
  • maximum length 64
A Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • pattern ^agentdef_[\s\S]+$
keyrequired
stringThe stable, human-authored Agent Definition key.
displayNamerequired
stringThe human-readable resource name.
statusrequired
stringThe current lifecycle status.
  • allowed values "active", "disabled"
configurationAuthorityrequired
stringThe one surface allowed to change this Agent Definition and publish its Versions.
  • allowed values "ApiManaged", "DashboardManaged"
testEnvironmentIdrequired
The Test Environment identifier, or null before it can be resolved.
Any of
string
All of
  • maximum length 64
A Cantora Environment identifier, prefixed with `env_`.
  • pattern ^env_[\s\S]+$
null
testAgentPrincipalIdrequired
The Test Agent Principal identifier, or null before it is created.
Any of
string
All of
  • maximum length 64
A Cantora Principal identifier, prefixed with `principal_`.
  • pattern ^principal_[\s\S]+$
null
testAgentStatusrequired
The Test Agent lifecycle status, or null before it is created.
Any of
string
null
currentAgentVersionIdrequired
The current Test Agent Version identifier, or null before the first activation.
Any of
string
All of
  • maximum length 64
A Cantora Agent Version identifier, prefixed with `agent_version_`.
  • pattern ^agent_version_[\s\S]+$
null
currentManifestrequired
The current Test Agent Version manifest, or null before the first activation.
Any of
AgentVersionManifest
null
currentManifestDigestrequired
The current Test Agent Version manifest digest, or null before the first activation.
Any of
string
null
currentTestAgentReleaseIdrequired
The current Test 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
currentTestAgentReleaseReasonrequired
The current Test Agent Release reason, or null before the first activation.
Any of
string
null
testReleaseGenerationrequired
integerThe current Test Agent Release generation, starting at zero before activation.
All of
  • minimum 0
testReleaseEtagrequired
stringThe strong ETag for the current Test Agent Release generation.
latestConfigurationRevisionIdrequired
The latest Configuration Revision for this Agent Definition, or null before an apply.
Any of
string
All of
  • maximum length 64
A Cantora Configuration Revision identifier, prefixed with `configuration_revision_`.
  • pattern ^configuration_revision_[\s\S]+$
null

AgentVersionManifest

object
  • unknown properties allowed false
schemaVersionrequired
stringThe Agent Version manifest schema identifier.
  • allowed values "config.cantora.ai/agent-version/v1alpha2"
instructionsrequired
stringThe complete natural-language instructions for the Agent Version.
All of
  • maximum length 262144
modelrequired
AgentVersionModelThe exact provider model and behavior settings pinned by the Agent Version.
toolsrequired
AgentVersionDependenciesThe tool keys the Agent Version may call.
requiredBindingsrequired
AgentVersionDependenciesThe configuration bindings the Agent Version requires at runtime.
budgetsrequired
AgentVersionBudgetsThe finite execution limits enforced for the Agent Version.

ConfigurationRevisionProgress

object
  • unknown properties allowed false
agentDefinitionrequired
stringWhether the Agent Definition step has completed.
  • allowed values "Pending", "Succeeded"
testAgentrequired
stringWhether the Test Agent step has completed.
  • allowed values "Pending", "Succeeded"
agentVersionrequired
stringWhether the Agent Version step has completed.
  • allowed values "Pending", "Succeeded"
testReleaserequired
stringThe desired Test Environment and activation reason.
  • allowed values "Pending", "Succeeded"

ConfigurationRevisionFailureJsonEncoding

object
  • unknown properties allowed false
coderequired
stringThe stable machine-readable condition code.
messagerequired
stringThe safe human-readable condition detail.

AgentVersionModel

Any of
object
  • unknown properties allowed false
providerrequired
stringThe model or Surface provider key.
  • allowed values "googleVertex"
modelrequired
stringThe exact provider model and behavior settings pinned by the Agent Version.
All of
  • minimum length 1
  • maximum length 256
settingsrequired
GoogleVertexModelSettingsThe provider-native settings that change model behavior.
object
  • unknown properties allowed false
providerrequired
stringThe model or Surface provider key.
  • allowed values "openai"
modelrequired
stringThe exact provider model and behavior settings pinned by the Agent Version.
All of
  • minimum length 1
  • maximum length 256
settingsrequired
OpenAiModelSettingsThe provider-native settings that change model behavior.

AgentVersionDependencies

array
Items
string
All of
  • minimum length 1
  • maximum length 100
  • pattern ^[a-z][a-z0-9_]*$
All of
  • at most items 100
  • unique items true

AgentVersionBudgets

object
  • unknown properties allowed false
maxModelStepsrequired
integerThe maximum number of model calls in one Run.
All of
  • maximum 100
  • minimum 1
maxToolCallsrequired
integerThe maximum number of tool calls in one Run.
All of
  • maximum 100
  • minimum 0
totalWallTimeMsrequired
integerThe maximum total Run duration in milliseconds.
All of
  • maximum 300000
  • minimum 1000
modelStepTimeMsrequired
integerThe maximum duration of one model step in milliseconds.
All of
  • maximum 300000
  • minimum 1000
streamStallTimeMsrequired
integerThe maximum duration without stream progress in milliseconds.
All of
  • maximum 300000
  • minimum 1000
maxInputTokensrequired
integerThe maximum number of model input tokens.
All of
  • maximum 10000000
  • minimum 1
maxOutputTokensrequired
integerThe maximum number of model output tokens.
All of
  • maximum 1000000
  • minimum 1
maxReasoningTokensrequired
integerThe maximum number of model reasoning tokens.
All of
  • maximum 1000000
  • minimum 0
maxTotalTokensrequired
integerThe maximum total model tokens in one Run.
All of
  • maximum 10000000
  • minimum 1
maxToolResultBytesrequired
integerThe maximum aggregate tool-result size in bytes.
All of
  • maximum 10000000
  • minimum 1
maxEstimatedCostMicrosrequired
integerThe maximum estimated model cost in millionths of the billing currency.
All of
  • maximum 1000000000
  • minimum 1

GoogleVertexModelSettings

object
  • unknown properties allowed false
thinkingLevelrequired
stringThe Google Vertex-native thinking level.
  • allowed values "minimal", "low", "medium", "high"

OpenAiModelSettings

object
  • unknown properties allowed false
reasoningEffortrequired
stringThe OpenAI-native reasoning effort.
  • allowed values "none", "low", "medium", "high", "xhigh", "max"
reasoningModerequired
stringThe OpenAI-native reasoning mode.
  • allowed values "standard", "pro"