Integrations API

MCP-compatible integration servers (tool providers) — fully live, not a stub. The lifecycle paths are connect/disconnect/reconnect, not start/stop/restart.

Endpoints

IntegrationRead is admin/operator/developer/viewer/auditor; IntegrationManage is admin/operator only. Removing, stopping, or restarting an integration is refused (issue #407 "provider drain guard") if live consumers still depend on its contracts.

GET /integrations

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/integrations

Response (200) — IntegrationInfo[]

{
  "integrations": [
    {
      "id": "postgresql-connector",
      "name": "PostgreSQL Connector",
      "description": "Read/write access to the claims database",
      "version": "2.1.0",
      "transport": "stdio",
      "status": "Running"
    }
  ]
}

status is one of "Installed", "Running", "Disconnected", "Disabled", or {"Error": "<message>"}.

POST /integrations/install

Installs from a local directory containing an integration.toml manifest.

curl -X POST -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "/opt/hoziron/integrations/github-connector", "key": "GITHUB_TOKEN_VALUE"}' \
  http://localhost:4200/integrations/install

Request Body

Response (201)

{"status": "installed", "name": "/opt/hoziron/integrations/github-connector"}

POST /integrations/{id}/connect

curl -X POST -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/integrations/postgresql-connector/connect

Response (200)

{"status": "connected", "id": "postgresql-connector"}

POST /integrations/{id}/disconnect

{"status": "disconnected", "id": "postgresql-connector"}

POST /integrations/{id}/reconnect

{"status": "connected", "id": "postgresql-connector"}

GET /integrations/{id}/status

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/integrations/postgresql-connector/status

Response (200)

{"id": "postgresql-connector", "status": "Running"}

Error (404 — not installed)

{"error": {"category": "NotFound", "message": "Integration not found: postgresql-connector", "details": {"integration_id": "postgresql-connector"}}}

GET /integrations/{id}/tools

{
  "id": "postgresql-connector",
  "tools": [
    {"name": "query", "description": "Execute a read-only SQL query", "input_schema": {}}
  ]
}

DELETE /integrations/{id}

Response (204 No Content)

Error (403 — provider drain guard)

Returned if a live consumer still depends on the integration's contracts (issue #407).

GET /contracts

List every contract's recorded binding to the integration that currently occupies it (ADR-051). Read-only — there is no POST/PUT on this route; bindings are established implicitly as a side effect of equipping a competency whose declared contract resolves to an installed integration. See contract.md for the CLI equivalent, and object-model.md for how a contract package (ADR-066) relates to this binding.

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/contracts

Response (200)

{
  "bindings": [
    {
      "contract": "claims-write",
      "integration_id": "claims-core-adapter",
      "bound_at": "2026-06-01T10:00:00Z",
      "bound_by": "system"
    }
  ]
}

bound_by is the operator identity that caused the binding, or "system" for an automatic first-resolution bind at equip time. There is no /contracts/{contract}/pins or /pins/promote route — a locally carrier-writable destination-identity pin store would be a bypass of the licence's egress allowlist, not a weaker copy of it. Destination pins live exclusively in the signed carrier licence (ADR-064).

GET /connectors/health

Reachability and latency for the dashboard Integrations region's fixed six-connector set (Issue #698): guidewire (Guidewire ClaimCenter), salesforce, docusign, s3, stripe, sso_okta. Probed concurrently, not sequentially, so one slow connector doesn't block the others.

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/connectors/health

Response (200)

{
  "connectors": [
    {"id": "guidewire", "name": "Guidewire ClaimCenter", "status": "Healthy", "latency_ms": 82, "error": null},
    {"id": "salesforce", "name": "Salesforce", "status": "Degraded", "latency_ms": 940, "error": null},
    {"id": "docusign", "name": "DocuSign", "status": "Unreachable", "latency_ms": null, "error": "connection refused"},
    {"id": "s3", "name": "S3", "status": "NotConfigured", "latency_ms": null, "error": null},
    {"id": "stripe", "name": "Stripe", "status": "NotConfigured", "latency_ms": null, "error": null},
    {"id": "sso_okta", "name": "SSO/Okta", "status": "NotConfigured", "latency_ms": null, "error": null}
  ]
}

status is one of Healthy (within latency budget), Degraded (reachable but over budget), Unreachable (configured but failed to respond), or NotConfigured (no reachability-check URL set for this connector — not a failure, just unwired; see the [connectors] config section in config-toml.md).

Related

• skills.md — skills expose tools the same way; both feed an agent's runtime tool allowlist
• catalog.md — installing integration packages from a registry instead of a local path