API v1

Connections API

Connections endpoints expose provider, display name, and health metadata for workspace connections. Credential material, OAuth tokens, refresh tokens, and auth headers are never returned.

Step 1

List connection metadata for inventory and health dashboards.

Step 2

Fetch one connection summary by id.

Step 3

Use connection health to decide whether workflows need operator attention.

Endpoints

GET/api/v1/connections?limit=10

List connection summaries without credential material.

Required scope: connections:read

curl https://www.finkmesh.com/api/v1/connections?limit=10 \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

{
  "data": [
    {
      "id": "conn_123",
      "provider": "slack",
      "name": "Sales Slack",
      "status": "connected",
      "lastCheckedAt": "2026-07-01T12:00:00.000Z"
    }
  ],
  "pagination": { "limit": 10, "hasMore": false, "nextCursor": null },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

GET/api/v1/connections/{connectionId}

Fetch one connection summary and current health state.

Required scope: connections:read

curl https://www.finkmesh.com/api/v1/connections/{connectionId} \
  -H "Authorization: Bearer $FINKMESH_TOKEN"

{
  "data": {
    "id": "conn_123",
    "provider": "slack",
    "name": "Sales Slack",
    "status": "connected"
  },
  "requestId": "req_...",
  "apiVersion": "2026-07-01"
}

No secrets

The API returns metadata only. Connection credentials stay encrypted and are never exposed through public API or MCP tools.

Health states

Status values are connected, needs_reauth, disconnected, error, and unknown. Treat needs_reauth, disconnected, and error as operator-action states.

Related Docs

Workflow API Security