Skip to content
CantoraAPI documentation
POST
/v1/organizations/{organizationId}/projects/{projectId}/agent-definitions/{agentDefinitionId}/versions

Publish or reuse an immutable Agent Version

Publish a content-addressed Agent Version, or return the existing Version when the normalized manifest is identical.

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]+$
agentDefinitionIdpathYes
The Agent Definition to address.
string
All of
  • maximum length 64
A Cantora Agent Definition identifier, prefixed with `agentdef_`.
  • pattern ^agentdef_[\s\S]+$

Request body

Required.

application/json
object
  • unknown properties allowed false
manifestrequired
AgentVersionManifestThe complete immutable Agent behavior and execution-budget declaration.
sourcerequired
AgentVersionSourceThe source revision and automation run that published this Version.
Publish the first immutable Agent Version
{
  "manifest": {
    "schemaVersion": "config.cantora.ai/agent-version/v1alpha2",
    "instructions": "Answer support questions using the approved knowledge sources and cite the evidence used.",
    "model": {
      "provider": "googleVertex",
      "model": "gemini-3.6-flash",
      "settings": {
        "thinkingLevel": "low"
      }
    },
    "tools": [],
    "requiredBindings": [],
    "budgets": {
      "maxModelSteps": 12,
      "maxToolCalls": 0,
      "totalWallTimeMs": 240000,
      "modelStepTimeMs": 90000,
      "streamStallTimeMs": 15000,
      "maxInputTokens": 100000,
      "maxOutputTokens": 16000,
      "maxReasoningTokens": 32000,
      "maxTotalTokens": 140000,
      "maxToolResultBytes": 1000000,
      "maxEstimatedCostMicros": 5000000
    }
  },
  "source": {
    "repository": "example.invalid/acme/support-agent",
    "commit": "0000000000000000000000000000000000000000",
    "path": "cantora/support-agent.json",
    "workflow": "publish-support-agent",
    "run": "example-1"
  }
}

Responses

200PublishedAgentVersion
application/json
PublishedAgentVersionJsonEncoding
Agent Version published
{
  "outcome": "created",
  "version": {
    "agentVersionId": "agent_version_00000000000000000000000000000001",
    "organizationId": "org_00000000000000000000000000000002",
    "projectId": "proj_00000000000000000000000000000001",
    "agentDefinitionId": "agentdef_00000000000000000000000000000001",
    "revision": 1,
    "manifest": {
      "schemaVersion": "config.cantora.ai/agent-version/v1alpha2",
      "instructions": "Answer support questions using the approved knowledge sources and cite the evidence used.",
      "model": {
        "provider": "googleVertex",
        "model": "gemini-3.6-flash",
        "settings": {
          "thinkingLevel": "low"
        }
      },
      "tools": [],
      "requiredBindings": [],
      "budgets": {
        "maxModelSteps": 12,
        "maxToolCalls": 0,
        "totalWallTimeMs": 240000,
        "modelStepTimeMs": 90000,
        "streamStallTimeMs": 15000,
        "maxInputTokens": 100000,
        "maxOutputTokens": 16000,
        "maxReasoningTokens": 32000,
        "maxTotalTokens": 140000,
        "maxToolResultBytes": 1000000,
        "maxEstimatedCostMicros": 5000000
      }
    },
    "manifestDigest": "d1211243559d67e3078ef4de78bbbedf0f64dfd6a7d8b39688459a961e67d687",
    "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

Reusable schemas

PublishedAgentVersionJsonEncoding

object
  • unknown properties allowed false
outcomerequired
stringWhether publication created a new Agent Version or reused identical content.
  • allowed values "created", "reused"
versionrequired
AgentVersionJsonEncodingThe immutable Agent Version returned by the publication.

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.

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.

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

AgentVersionJsonEncoding

object
  • unknown properties allowed false
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]+$
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]+$
revisionrequired
integerThe monotonically increasing revision within the Agent Definition.
All of
  • greater than 0
manifestrequired
AgentVersionManifestThe complete immutable Agent behavior and execution-budget declaration.
manifestDigestrequired
stringThe lowercase SHA-256 digest of the normalized manifest.
  • maximum length 64
  • minimum length 64
  • pattern ^[0-9a-f]{64}$
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

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"