FileRelayDocumentation
Try for Free

API Overview

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 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:

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:

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:

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

Collection (list):

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

Error Responses

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

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 List, retrieve, and retry documents
Repositories Manage source repositories
Destinations Manage destination connectors
Connections Wire sources to destinations
Certificates Inspect and manage ArchiveLink signing certificates
RFC Invoke SAP BAPIs through the JCo bridge
Request Viewer Query captured requests and the workspace audit log
Webhooks Configure and consume webhook events

Next Steps