Skip to content
CantoraAPI documentation
POST
/v1/organizations/{organizationId}/projects/{projectId}/environments/{environmentId}/surface-registrations

Register a Surface provider application in an Environment

Register an Organization-owned provider application as a delivery Surface in one Environment.

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

Request body

Required.

application/json
object
  • unknown properties allowed false
providerApplicationIdrequired
stringThe Organization-owned provider application to register in this Environment.
All of
  • maximum length 64
A Cantora provider application identifier, prefixed with `provider_app_`.
  • pattern ^provider_app_[\s\S]+$
displayNamerequired
stringThe human-readable Surface registration name.
  • maximum length 200
  • minimum length 1

Responses

201SurfaceRegistrationCreated
application/json
SurfaceRegistrationCreatedJsonEncoding
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

SurfaceRegistrationCreatedJsonEncoding

object
  • unknown properties allowed false
surfaceRegistrationIdrequired
stringThe Environment Surface registration identifier.
All of
  • maximum length 64
A Cantora Surface registration identifier, prefixed with `surface_`.
  • pattern ^surface_[\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]+$
providerApplicationIdrequired
stringThe Organization-owned provider application identifier.
All of
  • maximum length 64
A Cantora provider application identifier, prefixed with `provider_app_`.
  • pattern ^provider_app_[\s\S]+$
providerrequired
stringThe model or Surface provider key.
  • allowed values "slack"
providerAppIdrequired
stringThe provider's stable application identifier.
displayNamerequired
stringThe human-readable resource name.
statusrequired
stringThe current lifecycle status.
  • allowed values "active", "disabled"
capabilitiesrequired
SurfaceCapabilitiesThe delivery and interaction capabilities of the registered Surface.
conditionsrequired
SurfaceRegistrationConditionsConditions on the registration that require operator attention.
createdAtrequired
stringWhen the resource was created, in UTC.
  • format date-time

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.

SurfaceCapabilities

object
  • unknown properties allowed false
participantModelrequired
stringWhether a conversation has one participant or a shared audience.
  • allowed values "single", "multi"
addressingrequired
stringHow a participant addresses the Agent on this Surface.
  • allowed values "implicit", "mention", "explicit"
threadingrequired
stringHow the Surface groups replies into threads.
  • allowed values "none", "thread"
reactionsrequired
arrayThe provider-native reactions the Surface adapter can deliver.
Items
string
All of
  • minimum length 1
  • maximum length 64
  • pattern ^[!-~]+$
All of
  • unique items true
progressrequired
stringHow the Surface presents progress while work runs.
  • allowed values "none", "edit-in-place", "append", "stream"
approvalAffordancerequired
stringHow the Surface presents an approval request.
  • allowed values "none", "signed-interaction", "authenticated-view"
deliveryIdentityrequired
stringWhether delivery uses a provider-owned or Cantora-owned identity.
  • allowed values "provider-key", "cantora-key"
transportrequired
stringThe provider transport used to receive and deliver messages.
  • allowed values "webhook-and-call", "subscription"

SurfaceRegistrationConditions

array
Items
SurfaceRegistrationConditionJsonEncoding

SurfaceRegistrationConditionJsonEncoding

object
  • unknown properties allowed false
coderequired
stringThe stable machine-readable condition code.
  • allowed values "mixedTenantConversation"
providerIssuerrequired
stringThe provider account or workspace boundary.
All of
  • minimum length 1
  • maximum length 512
  • pattern ^[!-~]+$
providerConversationKeyrequired
stringThe provider's stable conversation address within its issuer.
All of
  • minimum length 1
  • maximum length 512
  • pattern ^[!-~]+$
existingTenantIdrequired
stringThe Tenant that already owns the provider conversation.
All of
  • maximum length 64
A Cantora Tenant identifier, prefixed with `tenant_`.
  • pattern ^tenant_[\s\S]+$
attemptedTenantIdrequired
stringThe Tenant that attempted to claim the provider conversation.
All of
  • maximum length 64
A Cantora Tenant identifier, prefixed with `tenant_`.
  • pattern ^tenant_[\s\S]+$
occurrenceCountrequired
integerHow many times the condition has been observed.
All of
  • greater than 0
firstObservedAtrequired
stringWhen the condition was first observed, in UTC.
  • format date-time
lastObservedAtrequired
stringWhen the condition was most recently observed, in UTC.
  • format date-time