---
title: Connections API
description: "API endpoints for managing connections (pipelines) that wire sources to destinations in FileRelay."
---

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`

```json
{
  "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:**

```json
{
  "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`

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

## Update Connection

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

**Request Body:**

```json
{
  "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`

```json
{
  "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
```

```json
{
  "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:

```json
{
  "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) |