Integration connections

The connection.* family (17 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.

Checkconnection.check

Validate the connection’s config + credential reachability. The actual off-box reachability test is STUBBED this beat (the connector data-sync engine is a later beat): the check confirms a credential EXISTS + DECRYPTS (proving the at-rest secret is intact, INV-7) and lands a verdict. A failed check sets status=ERROR + last_error (observability); a passing one leaves status unchanged (a check is not an enable). simulateFailure drives the ERROR path deterministically for the test/operator. WRITE (it may flip status to ERROR) per the catalogue check/sync row.

Input { id, simulateFailure? } (fields ending in ? are optional)

Call POST /v/connection.check with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.check.

Createconnection.create

Authors a DRAFT connection. If webhookSecret is supplied it is encrypted-before-write (INV-7) as the inbound-webhook HMAC secret (the governance seam, INBOUND). The credentials themselves are NOT on this row - they are credential.set rows (one connection may carry several labelled secrets). A duplicate name in the scope is a friendly Conflict (never a raw uq leak). Size-bound: webhookSecret is capped (anti blob-stuff, catalogue L174). scope defaults to WORKSPACE; actorId is required (and defaults to the caller) when scope is ACTOR, and must be omitted when scope is WORKSPACE.

Input { name, kind, provider, config?, webhookSecret?, scope?, actorId? } (fields ending in ? are optional)

Call POST /v/connection.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.create.

Deleteconnection.delete

Tear down a connection. Its credentials + egress-allow rows cascade by FK (migration 0029). The synced INTEGRATION data tables are RETAINED, not dropped (catalogue L177): the data_table.pipeline_connection_id FK is ON DELETE SET NULL, so those tables simply lose their connection pointer (their rows are never deleted). The number of orphaned tables is reported. RLS-scoped + explicit workspace predicate; a cross-workspace id reads back not-found.

Input { id } (fields ending in ? are optional)

Call POST /v/connection.delete with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Disableconnection.disable

Disable a connection (-> DISABLED) - halts sync WITHOUT losing cursor state (catalogue L176: the cursor column is left UNTOUCHED, so a later re-enable resumes). An already-DISABLED one is an idempotent no-op success. RLS-scoped + explicit workspace predicate.

Input { id } (fields ending in ? are optional)

Call POST /v/connection.disable with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.disable.

Enableconnection.enable

Enable a connection (-> ACTIVE). A DRAFT/DISABLED/ERROR connection moves to ACTIVE; an already-ACTIVE one is an idempotent no-op success. Clears last_error. RLS-scoped + explicit workspace predicate.

Input { id } (fields ending in ? are optional)

Call POST /v/connection.enable with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.enable.

Createconnection.ext.create

The frontend extension of the kernel pipeline_connection governance row (the cconn_ id is the natural 1:1 PK). INSERT ON CONFLICT(connection_id) DO NOTHING + re-read = idempotent. workspace_id from ctx; created_by_id from the acting human (rule 2).

Call POST /v/connection.ext.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.ext.create.

Deleteconnection.ext.delete

DELETE by connection_id in ctx.workspace_id (idempotent). Runs AFTER the kernel connection.delete cascades the governance row.

Call POST /v/connection.ext.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.ext.delete.

Updateconnection.ext.update

Keyed by connection_id (1:1) in ctx.workspace_id; naturally idempotent/no-op-if-absent. The optional ifWebhookToken match folds the legacy-webhook-token upgrade CAS.

Call POST /v/connection.ext.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.ext.update.

Getconnection.get

s one connection’s metadata + its credentials INVENTORY (masked - NEVER the secret). RLS-scoped + explicit workspace predicate. The webhook secret + credential ciphertext are NEVER returned (INV-7); only the presence flag + the masked hint.

Input { id } (fields ending in ? are optional)

Call POST /v/connection.get with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Createconnection.linkage.create

workspace_id from ctx; the connection must resolve in the workspace. (connection_id, stream_name, target_table_id) is UNIQUE -> Conflict.

Call POST /v/connection.linkage.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.linkage.create.

Deleteconnection.linkage.delete

Fenced by workspace_id (direct column).

Call POST /v/connection.linkage.delete with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.linkage.delete.

Updateconnection.linkage.update

Partial patch fenced by workspace_id. Supports an enriched_count INCREMENT (enrichedCountDelta) for the enrichment-service stats writes.

Call POST /v/connection.linkage.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.linkage.update.

Listconnection.list

Lists connections in the workspace (metadata only; secrets never appear). RLS-scoped + explicit workspace predicate (a cross-workspace connection is unreachable).

Input { status?, kind? } (fields ending in ? are optional)

Call POST /v/connection.list with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.list.

Createconnection.run.create

Fence the connection in ctx.workspace_id (pipeline_runs has no workspace_id). Mints + returns runId.

Call POST /v/connection.run.create with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.run.create.

Purgeconnection.run.purge

Only. Retention sweep: delete runs of the given statuses started before olderThan, fenced via the connection in ctx.workspace_id. Returns {count}. BEARERLESS.

Call POST /v/connection.run.purge with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Sweep Staleconnection.run.sweepStale

Only. Mark stale/orphan runs failed/cancelled: an explicit runIds[] OR a predicate (fromStatuses + optional staleBefore on last_heartbeat). Fence via the connection in ctx.workspace_id. Returns {count}. BEARERLESS.

Call POST /v/connection.run.sweepStale with a JSON body; returns JSON (or { error, code }). Not advertised over MCP (admin-only); reachable via the CLI and HTTP doors.

Updateconnection.run.update

Partial COALESCE update; fence via the connection in ctx.workspace_id. log-flusher writes high-frequency heartbeats - kept lean.

Call POST /v/connection.run.update with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool connection.run.update.