Get Document

get/v1/documents

Returns documents in the caller's workspace, optionally filtered by workspace id, external workspace id, and paginated. Read-only; no side effects. ## Filtering & sorting Filter via `POST /v1/records/query` (root `documents`) or the `filters` model; operators are gated by each field's data type. See [Filtering & sorting](../filtering-and-sorting). **Filterable fields** | Field | Type | Allowed operators | |---|---|---| | `bucket` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_document_summary` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_file_preview_url` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_invoices_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_routed_to` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_sourced_from` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_transactions_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `content_checksum` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `created_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `deleted_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `document_id` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `document_type` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `filename` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `local_file_name` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `path` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `pk` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `processing_error` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `processing_stage` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `processing_status` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `size` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `type` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `updated_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `uploaded_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | **Sortable fields:** `bucket`, `composite_document_summary`, `composite_file_preview_url`, `composite_invoices_list`, `composite_routed_to`, `composite_sourced_from`, `composite_transactions_list`, `content_checksum`, `created_at`, `deleted_at`, `document_id`, `document_type`, `filename`, `local_file_name`, `path`, `pk`, `processing_error`, `processing_stage`, `processing_status`, `size`, `type`, `updated_at`, `uploaded_at` (via `orderBy` / `sort`, `asc`|`desc`).

Requires a bearer token: Authorization: Bearer <token>.

Query parameters

NameTypeRequiredDescription
filter[workspace_id]string <uuid>NoRestrict to one workspace.e.g. 8f6b2c10-4a1e-4d2b-9c3a-1f0e7a5b6c21
filter[external_workspace_id]stringNoRestrict by external workspace identifier.e.g. foldspace-prod
filter[page]stringNo1-based page number.e.g. 1
filter[limit]stringNoPage size, 1 to 100.e.g. 25

Request

cURL
curl -X GET https://api.wellapp.ai/v1/documents \
  -H "Authorization: Bearer $WELL_API_TOKEN"

Responses

200 — A page of documents.

{
  "data": [
    {
      "type": "document",
      "document_id": "4e5f6071-8293-4a4b-95c6-d7e8f9a0b1c2",
      "id": "4e5f6071-8293-4a4b-95c6-d7e8f9a0b1c2",
      "attributes": {
        "filename": "anthropic-invoice-2026-05.pdf",
        "local_file_name": "doc_4e5f6071.pdf",
        "type": "application/pdf",
        "size": 84213,
        "workspace_id": "8f6b2c10-4a1e-4d2b-9c3a-1f0e7a5b6c21",
        "uploaded_at": "2026-05-04T18:20:00.000Z",
        "document_type": "380"
      },
      "links": {
        "download": "https://storage.wellapp.ai/signed/doc_4e5f6071?sig=abc123"
      },
      "relationships": {
        "collect": {
          "data": {
            "type": "collect",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        },
        "invoices": {
          "data": [
            {
              "type": "invoice",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        },
        "transaction_documents": {
          "data": [
            {
              "type": "transaction_document",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        }
      }
    }
  ]
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

403 — Forbidden

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

Complex Usage Example

Advanced Document Filtering with Full Context

This example demonstrates advanced filtering with multiple parameters, relationship inclusion, file type filtering, and sorting for retrieving documents:

curl -X GET "https://api.well.com/v1/documents?include=media,invoice&filter[workspace_id]=550e8400-e29b-41d4-a716-446655440000&filter[status]=completed&filter[file_type]=pdf&filter[uploaded_at][from]=2024-01-01T00:00:00Z&filter[uploaded_at][to]=2024-12-31T23:59:59Z&filter[processed_at][from]=2024-06-01T00:00:00Z&sort=-uploaded_at&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Filtering & sorting on related objects

Filter and sort on a related (included) object by nesting into the relationship — the same relationships you pass to include.

  • To-one relations nest directly: { "issuer": { "name": { "_eq": "Acme" } } }, and sort by a dot-path: "orderBy": { "field": "issuer.name", "direction": "asc" }.
  • To-many relations must be quantified with _some, _every, or _none: { "items": { "_some": { "quantity": { "_gt": 1 } } } }. They are not directly sortable (a to-many sort needs an aggregate proxy).
  • Composite composite_* columns are virtual — filter and sort on their underlying source fields, not on the composite.

Workspace row-level security applies at every hop, so a related-object filter never widens your tenant scope. Full operator set, deep-nesting rules, and pagination notes: Filtering & sorting.

This resource's related objects (the ones you can include) and how to filter or sort on each:

RelationshipCardinalityFilter on a fieldSort by a field
workspaceto-one (workspace){ "workspace": { "name": { "_eq": … } } }"field": "workspace.name" ✅
collectto-one (collect){ "collect": { "field_name": { "_eq": … } } }"field": "collect.field_name" ✅
source_workspace_connectorto-one (workspace_connector){ "source_workspace_connector": { "name": { "_eq": … } } }"field": "source_workspace_connector.name" ✅
invoicesto-many (invoice){ "invoices": { "_some": { "grand_total": { "_eq": … } } } }aggregate proxy only ⚠️
transaction_documentsto-many (transaction_document){ "transaction_documents": { "_some": { "field_name": { "_eq": … } } } }aggregate proxy only ⚠️

Replace field_name with any field of the related object. See its object-reference page for the full field list.

Filter by a to-one relation (and sort by it):

{
  "root": "documents",
  "whereClause": { "workspace": { "name": { "_ilike": "%acme%" } } },
  "orderBy": { "field": "workspace.name", "direction": "asc" }
}

Filter by a to-many relation (quantified — bare nesting is invalid):

{
  "root": "documents",
  "whereClause": { "invoices": { "_some": { "grand_total": { "_gt": 0 } } } }
}