VocalDocscontracts 1.65.0

Create a Connection

POST /v1/connections

PropertyValue
Operationcreate_connection
GroupConnections
Scopeintegrations:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited integrations.connection.create (mutation)
Released in1.60.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Creates a Connection to a Connector of the catalog at revision 1 with status pending_authorization (1.60.0). A planned or deprecated Connector, and a reserved Channel, are refused with capability_not_available; every other issue is a detail of validation_failed (ConnectionIssueCode), the base URL checked through the egress guard (egress_denied).

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the integrations:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/connections" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "clinic-ehr",
    "connector_id": "fhir_r4",
    "enabled_tools": [
      "book_appointment"
    ]
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: ConnectionCreateRequest.

FieldTypeRequiredDescription
allowed_environmentsarray of Environmentno["live"] when omitted.
base_urlConnectionBaseUrlnoRequired by a Connector whose manifest names a customer base URL, refused otherwise.
connector_idConnectorIdyes
connector_majorintegernoThe manifest's major version to pin; the catalog's current major when omitted.
enabled_toolsarray of ConnectorToolNameyes
nameConnectionNameyes
sandboxbooleannoFalse when omitted.
senderConnectionSenderInputnoRequired by a Connection that enables a send tool, refused for one that enables no messaging tool.

Responses

StatusContent typeShapeError codes
201application/jsonConnection
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed, capability_not_available
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is Connection.

FieldTypeRequiredDescription
allowed_environmentsarray of EnvironmentyesThe environments whose runs may use it; live only by default. A test run against a Connection that does not allow test executes the Connector's mock (integrations.md section 3).
auth_strategyConnectionAuthStrategyyes
authorized_atTimestamp or nullyes
base_urlConnectionBaseUrl or nullyes
connector_idConnectorId or nullyesThe Connector; null for an MCP server.
connector_majorinteger or nullyesThe major version of the Connector's manifest the Connection pins; null for an MCP server.
created_atTimestampyes
enabled_toolsarray of ConnectorToolNameyesThe Connector's tools the Organization allows, which set the scopes requested (integrations.md section 10); empty for an MCP server, whose registration's allowed_tools govern.
external_accountstring or nullyesThe external account authorized (a tenant id, an instance URL); null before.
granted_scopesarray of VendorScopeyesThe scopes the vendor granted at the last authorization; empty before.
idConnectionIdyes
mcp_server_idMcpServerId or nullyesThe MCP server registration whose credential the Connection holds; null for a Connector.
nameConnectionNameyes
object"connection"yes
organization_idOrganizationIdyes
originConnectionOriginyes
phi_attestationConnectionPhiAttestation or nullyesThe PHI attestation, or null; only an attested Connection may receive PHI.
requested_scopesarray of VendorScopeyesThe union of the scopes of enabled_tools; nothing more is requested.
revisionintegeryesCounts writes to the Connection; returned as the ETag and required in If-Match.
revoked_atTimestamp or nullyes
sandboxbooleanyesTrue for a vendor sandbox, which may allow test; a test Call never books a real appointment.
secret_hintstring or nullyesThe last characters of the stored key or token, or null; never the secret.
secret_versionintegeryesCounts the secrets stored; 0 before the first. A refresh write-back compares and sets it.
senderConnectionSender or nullyesThe sender of a messaging Connection; null otherwise.
statusConnectionStatusyes
status_reasonConnectionStatusReason or nullyesNull while active.
updated_atTimestampyes