---
title: Documents API
description: "API endpoints for listing, retrieving, and retrying documents in FileRelay."
---

# Documents API

The Documents API lets you query documents that have been received by FileRelay, inspect their delivery status, and retry failed deliveries.

## List Documents

Retrieve a paginated list of documents in the current workspace.

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

### Query Parameters

| Parameter    | Type    | Description                                          | Default |
|-------------|---------|------------------------------------------------------|---------|
| `page`      | integer | Page number                                          | 1       |
| `per_page`  | integer | Items per page (max 100)                             | 25      |
| `repo_id`   | string  | Filter by source repository ID                       | --      |
| `status`    | string  | Filter by status: `pending`, `delivered`, `failed`, `retrying` | -- |
| `date_from` | string  | Filter documents received on or after (ISO 8601)     | --      |
| `date_to`   | string  | Filter documents received on or before (ISO 8601)    | --      |

### Example Request

```bash
curl -X GET "https://filerelay.dev/api/acme/production/documents?repo_id=Z1&status=delivered&per_page=10" \
  -H "Authorization: Bearer fr_live_abc123def456" \
  -H "Accept: application/json"
```

### Example Response

```json
{
  "data": [
    {
      "id": "doc_a1b2c3d4",
      "type": "document",
      "attributes": {
        "doc_id": "4A3F8B2C1D7E9F0A",
        "repo_id": "Z1",
        "comp_id": "data",
        "content_type": "application/pdf",
        "size_bytes": 245780,
        "status": "delivered",
        "received_at": "2026-04-04T10:30:00Z",
        "deliveries": [
          {
            "destination_id": "dest_s3prod",
            "destination_name": "S3 Production Archive",
            "status": "delivered",
            "delivered_at": "2026-04-04T10:30:02Z",
            "attempts": 1
          },
          {
            "destination_id": "dest_sharepoint",
            "destination_name": "SharePoint Team Site",
            "status": "delivered",
            "delivered_at": "2026-04-04T10:30:03Z",
            "attempts": 1
          }
        ]
      }
    },
    {
      "id": "doc_e5f6g7h8",
      "type": "document",
      "attributes": {
        "doc_id": "7B2E9C4D5F1A3E8B",
        "repo_id": "Z1",
        "comp_id": "data",
        "content_type": "image/tiff",
        "size_bytes": 1024000,
        "status": "delivered",
        "received_at": "2026-04-04T10:28:15Z",
        "deliveries": [
          {
            "destination_id": "dest_s3prod",
            "destination_name": "S3 Production Archive",
            "status": "delivered",
            "delivered_at": "2026-04-04T10:28:17Z",
            "attempts": 1
          }
        ]
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 247
  }
}
```

## Get a Single Document

Retrieve details for a specific document by its FileRelay ID.

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

### Example Request

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

### Example Response

```json
{
  "data": {
    "id": "doc_a1b2c3d4",
    "type": "document",
    "attributes": {
      "doc_id": "4A3F8B2C1D7E9F0A",
      "repo_id": "Z1",
      "comp_id": "data",
      "content_type": "application/pdf",
      "size_bytes": 245780,
      "status": "delivered",
      "received_at": "2026-04-04T10:30:00Z",
      "metadata": {
        "sap_object_type": "BKPF",
        "sap_object_id": "1000012345672026",
        "ar_object": "ZCUSTOMINV"
      },
      "deliveries": [
        {
          "destination_id": "dest_s3prod",
          "destination_name": "S3 Production Archive",
          "status": "delivered",
          "delivered_at": "2026-04-04T10:30:02Z",
          "attempts": 1,
          "path": "/2026/04/04/4A3F8B2C1D7E9F0A.pdf"
        },
        {
          "destination_id": "dest_sharepoint",
          "destination_name": "SharePoint Team Site",
          "status": "delivered",
          "delivered_at": "2026-04-04T10:30:03Z",
          "attempts": 1,
          "path": "/Z1/invoice_4A3F8B2C1D7E9F0A.pdf"
        }
      ]
    }
  }
}
```

## Retry a Failed Document

Retry delivery for a document that has failed at one or more destinations. This re-queues the document for delivery to all failed destinations.

```
POST /api/{userSlug}/{workspaceSlug}/documents/:id/retry
```

### Example Request

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

### Example Response

```json
{
  "data": {
    "id": "doc_x9y8z7w6",
    "type": "document",
    "attributes": {
      "doc_id": "9C1D3E5F7A2B4D6E",
      "repo_id": "Z1",
      "status": "retrying",
      "received_at": "2026-04-03T15:42:00Z",
      "deliveries": [
        {
          "destination_id": "dest_s3prod",
          "destination_name": "S3 Production Archive",
          "status": "delivered",
          "delivered_at": "2026-04-03T15:42:02Z",
          "attempts": 1
        },
        {
          "destination_id": "dest_sharepoint",
          "destination_name": "SharePoint Team Site",
          "status": "retrying",
          "delivered_at": null,
          "attempts": 6
        }
      ]
    }
  }
}
```

### Notes

- Only documents with a `failed` status at one or more destinations can be retried
- Retrying a document does not re-deliver to destinations that already succeeded
- The retry follows the workspace retry settings (max retries, TTL)
- Requires **Member** or **Admin** API key permissions

## Document Statuses

| Status     | Description                                               |
|-----------|-----------------------------------------------------------|
| `pending`  | Document received, delivery not yet started               |
| `delivered`| All destinations received the document successfully       |
| `retrying` | At least one destination is being retried                 |
| `failed`   | At least one destination failed after all retry attempts  |
| `discarded` | No destination is wired to the source — the document was acknowledged to SAP but not retained or forwarded |

## Next Steps

- [Repositories API](/docs/api/repositories) -- Manage source repositories
- [Destinations API](/docs/api/destinations) -- Manage destination connectors
- [Webhook Events](/docs/api/webhooks) -- Get real-time delivery notifications