Skip to content
CantoraAPI documentation
POST
/v1/organizations/{organizationId}/integrations/{integrationId}/versions

Publish an immutable Integration Version

Validate, normalize, embed, and atomically publish a standard HTTP contract, or reuse an identical retry.

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]+$
integrationIdpathYes
The stable Integration lineage to address.
stringA Cantora Integration identifier, prefixed with `integration_`.
  • maximum length 64
  • pattern ^integration_[\s\S]+$

Request body

Required.

application/json
object
  • unknown properties allowed false
requestIdrequired
stringThe UUID identifying this exact immutable publication attempt.
  • maximum length 36
  • minimum length 36
  • pattern ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
manifestrequired
IntegrationVersionManifestThe complete credential-free standard HTTP service contract.
sourcerequired
DataIntegrationVersionSourceThe source revision and automation run that published this Version.

Responses

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

Reusable schemas

PublishedDataIntegrationVersionEncoded

object
  • unknown properties allowed false
outcomerequired
stringWhether publication created a Version or reused an identical request.
  • allowed values "created", "reused"
versionrequired
DataIntegrationVersionEncodedThe immutable Integration Version returned by publication.

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.

IntegrationVersionManifest

object
  • unknown properties allowed false
schemaVersionrequired
stringThe Agent Version manifest schema identifier.
  • allowed values "config.cantora.ai/integration-version/v1alpha1"
adapterContractKeyrequired
stringThe reviewed provider-neutral adapter contract selected by this Version.
  • allowed values "standardHttp"
adapterAbiVersionrequired
stringThe exact reviewed runtime adapter ABI required by this Version.
  • allowed values "v1alpha1"
serviceSummaryrequired
stringThe compact service description always available to the Agent.
  • maximum length 2000
  • minimum length 1
baseUrlrequired
stringThe credential-free absolute HTTPS base URL for this service Version.
  • maximum length 4000
  • minimum length 1
authenticationrequired
StaticHeaderAuthenticationHow a scoped Connection credential is applied to standard HTTP requests.
embeddingrequired
IntegrationEmbeddingConfigurationThe exact embedding space used for hybrid API-reference retrieval.
operationsrequired
arrayThe complete immutable operation documents published in this Version.
  • at most items 1000
  • at least items 1
Items
IntegrationOperationDocument

DataIntegrationVersionSource

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

DataIntegrationVersionEncoded

object
  • unknown properties allowed false
integrationVersionIdrequired
stringThe immutable Integration Version identifier.
  • maximum length 64
  • pattern ^integration_version_[\s\S]+$
organizationIdrequired
stringThe Organization identifier.
  • maximum length 64
  • pattern ^org_[\s\S]+$
integrationIdrequired
stringThe stable Organization-scoped Integration identifier.
  • maximum length 64
  • pattern ^integration_[\s\S]+$
revisionrequired
integerThe monotonically increasing revision within this Integration lineage.
  • greater than 0
manifestrequired
IntegrationVersionManifestThe complete immutable standard HTTP service contract.
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.
  • maximum length 64
  • pattern ^principal_[\s\S]+$
sourcerequired
DataIntegrationVersionSourceThe source revision and automation provenance.
createdAtrequired
stringWhen the resource was created, in UTC.
  • format date-time

StaticHeaderAuthentication

object
  • unknown properties allowed false
typerequired
stringThe closed contract behavior type.
  • allowed values "staticHeader"
headerNamerequired
stringThe permitted HTTP header used by this contract behavior, or null when unsupported.
  • maximum length 256
  • minimum length 1
valuePrefixrequired
stringThe non-secret value prepended to the Connection credential in the request header.
  • maximum length 256

IntegrationEmbeddingConfiguration

object
  • unknown properties allowed false
providerrequired
stringThe model, Surface, or integration provider key.
  • allowed values "googleVertex"
modelrequired
stringThe exact provider model and behavior settings pinned by the Agent Version.
  • allowed values "gemini-embedding-001"
dimensionsrequired
numberThe exact vector dimensions used for API-reference retrieval.
  • allowed values 1536

IntegrationOperationDocument

object
  • unknown properties allowed false
keyrequired
stringThe stable operation key within this Integration Version.
  • maximum length 100
  • minimum length 1
  • pattern ^[a-z][a-z0-9_]*$
intendedUserequired
stringWhen the Agent should use this operation.
  • maximum length 20000
  • minimum length 1
searchTermsrequired
arrayDeterministic terms used to retrieve this complete operation document.
  • at most items 100
  • unique items true
Items
string
  • maximum length 256
  • minimum length 1
methodrequired
stringThe HTTP method for this operation.
  • allowed values "GET", "POST", "PUT", "PATCH", "DELETE"
pathTemplaterequired
stringThe URL path template relative to the service base URL.
  • maximum length 2000
  • minimum length 1
parametersrequired
arrayThe complete path, query, and header parameters for this operation.
  • at most items 100
Items
IntegrationOperationParameter
requestSchemarequired
The fully resolved JSON Schema for the request body, or null when no body is accepted.
Any of
ResolvedJsonSchemaDocumentEncoded
null
responseSchemarequired
The fully resolved JSON Schema for a successful response, or null when none is defined.
Any of
ResolvedJsonSchemaDocumentEncoded
null
responseNotesrequired
stringHow to interpret the provider response.
  • maximum length 20000
  • minimum length 1
errorNotesrequired
arrayProvider errors and response conditions the caller must handle.
  • at most items 100
Items
string
  • maximum length 20000
  • minimum length 1
paginationrequired
IntegrationPaginationContractHow this operation paginates and how callers should continue it.
sideEffectrequired
stringWhether this operation is read-only, an idempotent write, or a non-idempotent write.
  • allowed values "readOnly", "idempotentWrite", "nonIdempotentWrite"
idempotencyKeyrequired
IntegrationIdempotencyKeyBehaviorWhether and how this operation accepts an idempotency key.
safeRetryConditionsrequired
stringThe exact conditions under which generated code may retry this operation.
  • maximum length 20000
  • minimum length 1
rateLimitGuidancerequired
stringHow generated code should respond to provider rate limits.
  • maximum length 20000
  • minimum length 1
examplesrequired
arrayBounded request and response examples for this operation.
  • at most items 10
Items
IntegrationOperationExample

IntegrationOperationParameter

object
  • unknown properties allowed false
namerequired
stringThe human-readable resource name.
  • maximum length 256
  • minimum length 1
locationrequired
stringWhere this parameter appears in the HTTP request.
  • allowed values "path", "query", "header"
requiredrequired
booleanWhether the parameter must be present.
descriptionrequired
stringA human-readable explanation of this contract element.
  • maximum length 20000
  • minimum length 1
schemarequired
ResolvedJsonSchemaDocumentEncodedThe fully resolved JSON Schema for this parameter.

ResolvedJsonSchemaDocumentEncoded

IntegrationPaginationContract

object
  • unknown properties allowed false
stylerequired
stringThe pagination style implemented by this operation.
  • allowed values "none", "cursor", "offset", "page", "link"
guidancerequired
stringImplementation guidance for this behavior.
  • maximum length 20000
  • minimum length 1

IntegrationIdempotencyKeyBehavior

object
  • unknown properties allowed false
supportedrequired
booleanWhether this optional contract behavior is supported.
headerNamerequired
The permitted HTTP header used by this contract behavior, or null when unsupported.
Any of
string
  • maximum length 256
  • minimum length 1
null
guidancerequired
stringImplementation guidance for this behavior.
  • maximum length 20000
  • minimum length 1

IntegrationOperationExample

object
  • unknown properties allowed false
namerequired
stringThe human-readable resource name.
  • maximum length 256
  • minimum length 1
descriptionrequired
stringA human-readable explanation of this contract element.
  • maximum length 20000
  • minimum length 1
requestrequired
IntegrationJsonValueEncodedThe example request value.
responserequired
IntegrationJsonValueEncodedThe example response value.

IntegrationJsonValueEncoded