---
title: Destinations API
description: "API endpoints for listing, creating, updating, deleting, and testing destination connectors in FileRelay."
---

# Destinations API

The Destinations API lets you manage destination connectors in your FileRelay workspace. Each destination represents a cloud storage service or target where documents are delivered.

## List Destinations

Retrieve all destinations in the current workspace.

```
GET /api/{userSlug}/{workspaceSlug}/destinations
```

### Query Parameters

| Parameter  | Type    | Description                        | Default |
|-----------|---------|-------------------------------------|---------|
| `page`    | integer | Page number                         | 1       |
| `per_page`| integer | Items per page (max 100)            | 25      |
| `type`    | string  | Filter by connector type (e.g., `s3`, `azure_blob`, `sharepoint`, `sftp`) | -- |

### Example Request

```bash
curl -X GET "https://filerelay.dev/api/acme/production/destinations" \
  -H "Authorization: Bearer fr_live_abc123def456" \
  -H "Accept: application/json"
```

### Example Response

```json
{
  "data": [
    {
      "id": "dest_s3prod",
      "type": "destination",
      "attributes": {
        "name": "S3 Production Archive",
        "connector_type": "s3",
        "status": "connected",
        "config": {
          "bucket": "company-sap-archive",
          "region": "us-east-1",
          "prefix": "archivelink/"
        },
        "created_at": "2026-01-15T08:30:00Z",
        "updated_at": "2026-03-20T14:00:00Z"
      }
    },
    {
      "id": "dest_sharepoint",
      "type": "destination",
      "attributes": {
        "name": "SharePoint Team Site",
        "connector_type": "sharepoint",
        "status": "connected",
        "config": {
          "site_url": "https://company.sharepoint.com/sites/finance",
          "document_library": "SAP Documents"
        },
        "created_at": "2026-02-10T10:00:00Z",
        "updated_at": "2026-04-01T09:00:00Z"
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 2
  }
}
```

## Get a Single Destination

Retrieve details for a specific destination.

```
GET /api/{userSlug}/{workspaceSlug}/destinations/:id
```

### Example Request

```bash
curl -X GET "https://filerelay.dev/api/acme/production/destinations/dest_s3prod" \
  -H "Authorization: Bearer fr_live_abc123def456" \
  -H "Accept: application/json"
```

### Example Response

```json
{
  "data": {
    "id": "dest_s3prod",
    "type": "destination",
    "attributes": {
      "name": "S3 Production Archive",
      "connector_type": "s3",
      "status": "connected",
      "config": {
        "bucket": "company-sap-archive",
        "region": "us-east-1",
        "prefix": "archivelink/"
      },
      "connections": [
        {
          "id": "conn_111",
          "source_repo_id": "Z1",
          "source_name": "Production ECC Invoices",
          "status": "active"
        }
      ],
      "created_at": "2026-01-15T08:30:00Z",
      "updated_at": "2026-03-20T14:00:00Z"
    }
  }
}
```

## Create a Destination

Create a new destination connector.

```
POST /api/{userSlug}/{workspaceSlug}/destinations
```

### Request Body

| Field            | Type   | Required | Description                                            |
|-----------------|--------|----------|--------------------------------------------------------|
| `name`          | string | Yes      | Display name for the destination                       |
| `connector_type`| string | Yes      | Connector type (see supported types below)             |
| `config`        | object | Yes      | Connector-specific configuration (varies by type)      |
| `credentials`   | object | Yes      | Connector-specific credentials (varies by type)        |

### Supported Connector Types

| Type             | Description           |
|------------------|-----------------------|
| `s3`             | Amazon S3             |
| `azure_blob`     | Azure Blob Storage    |
| `sharepoint`     | SharePoint Online     |
| `google_drive`   | Google Drive          |
| `sftp`           | SFTP Server           |
| `email`          | Email notification    |
| `webhook`        | HTTP Webhook          |

### Example Request (S3)

```bash
curl -X POST "https://filerelay.dev/api/acme/production/destinations" \
  -H "Authorization: Bearer fr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "S3 EU Archive",
    "connector_type": "s3",
    "config": {
      "bucket": "company-sap-archive-eu",
      "region": "eu-west-1",
      "prefix": "documents/"
    },
    "credentials": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
  }'
```

### Example Response

```json
{
  "data": {
    "id": "dest_neweu01",
    "type": "destination",
    "attributes": {
      "name": "S3 EU Archive",
      "connector_type": "s3",
      "status": "connected",
      "config": {
        "bucket": "company-sap-archive-eu",
        "region": "eu-west-1",
        "prefix": "documents/"
      },
      "created_at": "2026-04-04T11:30:00Z",
      "updated_at": "2026-04-04T11:30:00Z"
    }
  }
}
```

Returns `201 Created` on success. Credentials are never returned in API responses.

## Update a Destination

Update an existing destination's configuration or credentials.

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

### Request Body

| Field            | Type   | Required | Description                                  |
|-----------------|--------|----------|----------------------------------------------|
| `name`          | string | No       | Updated display name                         |
| `config`        | object | No       | Updated configuration (merged with existing) |
| `credentials`   | object | No       | Updated credentials (replaces existing)      |

### Example Request

```bash
curl -X PATCH "https://filerelay.dev/api/acme/production/destinations/dest_neweu01" \
  -H "Authorization: Bearer fr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "S3 EU Archive - Frankfurt",
    "config": {
      "prefix": "sap-docs/"
    }
  }'
```

### Example Response

```json
{
  "data": {
    "id": "dest_neweu01",
    "type": "destination",
    "attributes": {
      "name": "S3 EU Archive - Frankfurt",
      "connector_type": "s3",
      "status": "connected",
      "config": {
        "bucket": "company-sap-archive-eu",
        "region": "eu-west-1",
        "prefix": "sap-docs/"
      },
      "created_at": "2026-04-04T11:30:00Z",
      "updated_at": "2026-04-04T11:45:00Z"
    }
  }
}
```

Returns `200 OK` on success.

## Delete a Destination

Permanently delete a destination. Any connections using this destination are also removed.

```
DELETE /api/{userSlug}/{workspaceSlug}/destinations/:id
```

### Example Request

```bash
curl -X DELETE "https://filerelay.dev/api/acme/production/destinations/dest_neweu01" \
  -H "Authorization: Bearer fr_live_abc123def456"
```

Returns `204 No Content` on success.

**Warning:** This action is irreversible. Documents already delivered to this destination are not affected at the destination, but no new documents will be delivered.

## Test Connection

Test connectivity to a destination without creating it, or test an existing destination's connection.

```
POST /api/{userSlug}/{workspaceSlug}/destinations/test
```

### Request Body

For testing a new configuration before creating:

```bash
curl -X POST "https://filerelay.dev/api/acme/production/destinations/test" \
  -H "Authorization: Bearer fr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "connector_type": "s3",
    "config": {
      "bucket": "company-sap-archive-eu",
      "region": "eu-west-1",
      "prefix": "documents/"
    },
    "credentials": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    }
  }'
```

### Example Response (Success)

```json
{
  "data": {
    "status": "success",
    "message": "Successfully connected to S3 bucket 'company-sap-archive-eu' in eu-west-1."
  }
}
```

### Example Response (Failure)

```json
{
  "data": {
    "status": "failed",
    "message": "Access denied. The provided credentials do not have permission to write to bucket 'company-sap-archive-eu'."
  }
}
```

The test endpoint verifies that FileRelay can authenticate and write to the destination. It does not create any persistent resources.

## Next Steps

- [Repositories API](/docs/api/repositories) -- Manage source repositories
- [Documents API](/docs/api/documents) -- Query delivered documents
- [Connections Overview](/docs/connections/overview) -- Wire sources to destinations