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

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

Example Response

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

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

Example Response

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

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

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

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

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

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:

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)

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

Example Response (Failure)

{
  "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 -- Manage source repositories
Documents API -- Query delivered documents
Connections Overview -- Wire sources to destinations