Connections API

Connections (pipelines) wire sources (repositories) to destinations (connectors). When a document arrives at a source, it's forwarded to all destinations linked via active connections.

List Connections

GET /api/{userSlug}/{workspaceSlug}/connections

Query Parameters:

Parameter	Type	Description
is_active	boolean	Filter by active/inactive status

Response: 200 OK

{
  "data": [
    {
      "id": "01kn...",
      "name": "Invoice Pipeline",
      "is_active": true,
      "repositories": [
        { "id": "01kn...", "repo_id": "Z1", "description": "FI Invoices" }
      ],
      "destinations": [
        { "id": "01kn...", "type": "s3", "name": "S3 Archive" },
        { "id": "01kn...", "type": "email", "name": "AP Notifications" }
      ],
      "settings": {},
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-01T10:00:00Z"
    }
  ]
}

Get Connection

GET /api/{userSlug}/{workspaceSlug}/connections/:id

Response: 200 OK

Returns a single connection object with its linked repositories and destinations.

Create Connection

POST /api/{userSlug}/{workspaceSlug}/connections

Request Body:

{
  "name": "Invoice Pipeline",
  "is_active": true,
  "repository_ids": ["01kn..."],
  "destination_ids": ["01kn...", "01kn..."]
}

Field	Type	Required	Description
name	string	Yes	Display name for the connection
is_active	boolean	No	Whether the pipeline is active (default: true)
repository_ids	array	Yes	Array of repository IDs to wire as sources
destination_ids	array	Yes	Array of destination IDs to wire as targets
settings	object	No	Additional pipeline settings

Response: 201 Created

{
  "data": {
    "id": "01kn...",
    "name": "Invoice Pipeline",
    "is_active": true,
    "repositories": [...],
    "destinations": [...]
  }
}

Update Connection

PATCH /api/{userSlug}/{workspaceSlug}/connections/:id

Request Body:

{
  "name": "Updated Pipeline Name",
  "is_active": false,
  "repository_ids": ["01kn..."],
  "destination_ids": ["01kn...", "01kn...", "01kn..."]
}

All fields are optional. Only include the fields you want to change. Passing repository_ids or destination_ids replaces the entire set (not a merge).

Response: 200 OK

Delete Connection

DELETE /api/{userSlug}/{workspaceSlug}/connections/:id

Response: 200 OK

{
  "message": "Connection deleted"
}

Toggle Connection Active Status

A shorthand for enabling or disabling a pipeline without changing its configuration:

PATCH /api/{userSlug}/{workspaceSlug}/connections/:id

{
  "is_active": false
}

When a connection is inactive, documents arriving at its linked repositories are still received and stored, but they are not forwarded to the connection's destinations.

Fan-Out Example

To create a fan-out pipeline where repository Z1 forwards to S3, email, and Slack simultaneously:

{
  "name": "FI Fan-Out",
  "repository_ids": ["repo-id-z1"],
  "destination_ids": [
    "dest-id-s3-archive",
    "dest-id-email-ap",
    "dest-id-slack-alerts"
  ]
}

Each destination receives the document independently. If one destination fails, the others still succeed. Delivery status is tracked per-destination in the document's delivery_status field.

Error Responses

Status	Description
400	Invalid request body or missing required fields
404	Connection not found or belongs to another workspace
422	Validation failed (e.g. invalid repository or destination IDs)