---
title: API Overview
description: "Introduction to the FileRelay REST API, including base URL, authentication, response format, rate limits, and versioning."
---

# API Overview

The FileRelay API provides programmatic access to your workspace's documents, repositories, destinations, and connections. It uses RESTful conventions with JSON request and response bodies.

## Base URL

All API requests are made to:

```
https://filerelay.dev/api/{userSlug}/{workspaceSlug}
```

`{userSlug}` is the **workspace owner's** slug (the user who created the workspace) and `{workspaceSlug}` is the workspace's slug. Both come from the dashboard URL and are visible in the workspace switcher.

All endpoints require HTTPS. Plain HTTP requests are rejected.

## Authentication

Every API request must include a valid API key in the `Authorization` header using the Bearer scheme:

```
Authorization: Bearer fr_live_abc123def456...
```

Tokens are tied to a **user**, not a workspace. The same token can address any workspace that user belongs to by changing `{userSlug}/{workspaceSlug}` in the path. See [API Authentication](/docs/api/authentication) for details on creating and managing API keys.

## Request Format

- **Content-Type**: Send `application/json` for request bodies
- **Accept**: Responses are always `application/json`
- **Workspace addressing**: Every workspace-scoped request includes `{userSlug}/{workspaceSlug}` in the path. The API resolves the workspace, then checks that the calling user is a member with sufficient role.

Example request:

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

### Discovering Your Workspaces

To list the workspaces the current token can address:

```bash
curl -X GET https://filerelay.dev/api/me/workspaces \
  -H "Authorization: Bearer fr_live_abc123def456"
```

Returns the canonical `{userSlug}/{workspaceSlug}` pair and the caller's role for each workspace. Useful after a workspace rename or ownership transfer changes the URL.

## Response Format

All responses follow a consistent JSON structure.

### Successful Responses

Single resource:

```json
{
  "data": {
    "id": "doc_abc123",
    "type": "document",
    "attributes": {
      "doc_id": "4A3F8B2C1D7E9F0A",
      "repo_id": "Z1",
      "status": "delivered",
      "created_at": "2026-04-04T10:30:00Z"
    }
  }
}
```

Collection (list):

```json
{
  "data": [
    { "id": "doc_abc123", "type": "document", "attributes": { ... } },
    { "id": "doc_def456", "type": "document", "attributes": { ... } }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 142
  }
}
```

### Error Responses

```json
{
  "error": {
    "code": "validation_error",
    "message": "The repo_id field is required.",
    "details": {
      "repo_id": ["The repo_id field is required."]
    }
  }
}
```

### HTTP Status Codes

| Code | Meaning                                           |
|------|--------------------------------------------------|
| 200  | Success                                          |
| 201  | Resource created                                 |
| 204  | Success, no content (e.g., after delete)         |
| 400  | Bad request (invalid parameters)                 |
| 401  | Unauthorized (missing or invalid API key)        |
| 403  | Forbidden (caller's workspace role is too low for this action) |
| 404  | Resource not found, or workspace not addressable by this token |
| 422  | Validation error                                 |
| 429  | Rate limit exceeded                              |
| 500  | Internal server error                            |

A `404` is returned (rather than `403`) when the token's user is not a member of the addressed `{userSlug}/{workspaceSlug}` workspace, to avoid leaking the existence of workspaces the caller cannot see.

## Pagination

List endpoints return paginated results. Use these query parameters to control pagination:

| Parameter  | Default | Description                    |
|-----------|---------|--------------------------------|
| `page`    | 1       | Page number                    |
| `per_page`| 25      | Items per page (max 100)       |

The `meta` object in the response includes `current_page`, `per_page`, and `total` counts.

```bash
curl "https://filerelay.dev/api/acme/production/documents?page=2&per_page=50" \
  -H "Authorization: Bearer fr_live_abc123def456"
```

## Rate Limits

API requests are rate-limited per API key. Default limits are sized for typical SAP archiving workloads and can be adjusted per deployment — contact your FileRelay admin if you need them raised.

When you exceed the rate limit, the API returns a `429 Too Many Requests` response with headers indicating when you can retry:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1775405100
```

## Versioning

The API has no version segment in the URL. Our compatibility promise:

- **Additive changes** (new endpoints, new optional fields, new enum values) ship continuously and do not require any action.
- **Breaking changes** are gated behind an optional `X-FileRelay-Api-Version` header carrying an ISO date. Without the header, your requests stay on the latest stable behavior at the time you first started calling the API; we pin you forward only with notice.

```
X-FileRelay-Api-Version: 2026-04-01
```

A breaking change becomes the new "stable" no sooner than 90 days after announcement, and the previous behavior remains addressable via the header for at least 12 months.

## Available Endpoints

| Endpoint                                       | Description                                                  |
|------------------------------------------------|--------------------------------------------------------------|
| [Documents](/docs/api/documents)               | List, retrieve, and retry documents                          |
| [Repositories](/docs/api/repositories)         | Manage source repositories                                   |
| [Destinations](/docs/api/destinations)         | Manage destination connectors                                |
| [Connections](/docs/api/connections)           | Wire sources to destinations                                 |
| [Certificates](/docs/api/certificates)         | Inspect and manage ArchiveLink signing certificates          |
| [RFC](/docs/api/rfc)                           | Invoke SAP BAPIs through the JCo bridge                      |
| [Request Viewer](/docs/api/request-viewer)     | Query captured requests and the workspace audit log          |
| [Webhooks](/docs/api/webhooks)                 | Configure and consume webhook events                         |

## Next Steps

- [API Authentication](/docs/api/authentication) -- Create and manage API keys
- [Documents API](/docs/api/documents) -- Query documents and delivery status
- [Webhook Events](/docs/api/webhooks) -- Receive real-time notifications