Create a Connection
POST /v1/connections
| Property | Value |
|---|---|
| Operation | create_connection |
| Group | Connections |
| Scope | integrations:write |
| Route class | control |
| Idempotency | Idempotency-Key accepted: a retry with the same key replays the first answer |
| Audit | Audited integrations.connection.create (mutation) |
| Released in | 1.60.0 |
| Phase 0 host | Served (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"
]
}'const response = await fetch(`${process.env.VOCAL_API}/v1/connections`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "clinic-ehr",
"connector_id": "fhir_r4",
"enabled_tools": [
"book_appointment"
]
}),
});
console.log(response.status, await response.text());import os
import uuid
import requests
response = requests.post(
f"{os.environ['VOCAL_API']}/v1/connections",
headers={
"Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"name": "clinic-ehr",
"connector_id": "fhir_r4",
"enabled_tools": [
"book_appointment",
],
},
)
print(response.status_code, response.text)Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key | header | string | no | A 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.
| Field | Type | Required | Description |
|---|---|---|---|
allowed_environments | array of Environment | no | ["live"] when omitted. |
base_url | ConnectionBaseUrl | no | Required by a Connector whose manifest names a customer base URL, refused otherwise. |
connector_id | ConnectorId | yes | |
connector_major | integer | no | The manifest's major version to pin; the catalog's current major when omitted. |
enabled_tools | array of ConnectorToolName | yes | |
name | ConnectionName | yes | |
sandbox | boolean | no | False when omitted. |
sender | ConnectionSenderInput | no | Required by a Connection that enables a send tool, refused for one that enables no messaging tool. |
Responses
| Status | Content type | Shape | Error codes |
|---|---|---|---|
201 | application/json | Connection | |
400 | application/json | ErrorEnvelope | invalid_request |
401 | application/json | ErrorEnvelope | unauthenticated |
403 | application/json | ErrorEnvelope | forbidden, org_suspended |
409 | application/json | ErrorEnvelope | idempotency_in_progress, idempotency_key_reused |
422 | application/json | ErrorEnvelope | validation_failed, capability_not_available |
429 | application/json | ErrorEnvelope | rate_limited |
500 | application/json | ErrorEnvelope | internal_error |
Fields of the 201 answer
The shape is Connection.
| Field | Type | Required | Description |
|---|---|---|---|
allowed_environments | array of Environment | yes | The 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_strategy | ConnectionAuthStrategy | yes | |
authorized_at | Timestamp or null | yes | |
base_url | ConnectionBaseUrl or null | yes | |
connector_id | ConnectorId or null | yes | The Connector; null for an MCP server. |
connector_major | integer or null | yes | The major version of the Connector's manifest the Connection pins; null for an MCP server. |
created_at | Timestamp | yes | |
enabled_tools | array of ConnectorToolName | yes | The 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_account | string or null | yes | The external account authorized (a tenant id, an instance URL); null before. |
granted_scopes | array of VendorScope | yes | The scopes the vendor granted at the last authorization; empty before. |
id | ConnectionId | yes | |
mcp_server_id | McpServerId or null | yes | The MCP server registration whose credential the Connection holds; null for a Connector. |
name | ConnectionName | yes | |
object | "connection" | yes | |
organization_id | OrganizationId | yes | |
origin | ConnectionOrigin | yes | |
phi_attestation | ConnectionPhiAttestation or null | yes | The PHI attestation, or null; only an attested Connection may receive PHI. |
requested_scopes | array of VendorScope | yes | The union of the scopes of enabled_tools; nothing more is requested. |
revision | integer | yes | Counts writes to the Connection; returned as the ETag and required in If-Match. |
revoked_at | Timestamp or null | yes | |
sandbox | boolean | yes | True for a vendor sandbox, which may allow test; a test Call never books a real appointment. |
secret_hint | string or null | yes | The last characters of the stored key or token, or null; never the secret. |
secret_version | integer | yes | Counts the secrets stored; 0 before the first. A refresh write-back compares and sets it. |
sender | ConnectionSender or null | yes | The sender of a messaging Connection; null otherwise. |
status | ConnectionStatus | yes | |
status_reason | ConnectionStatusReason or null | yes | Null while active. |
updated_at | Timestamp | yes |