---
title: Search documents
sidebar_label: Search documents
sidebar_position: 3
description: "List the documents you can read, newest first, with paging and sorting."
---

# Search documents

| Method | Path |
| --- | --- |
| `GET` | `/document` |

[Authentication](/authentication) · [Access policies](/access-policies) · [Files and documents](/files-and-documents)

Lists the documents you can read, newest first by default. Use it to build a file list.

**Auth:** Bearer token. The search runs with your token, so the access policy must allow `DocumentReference:search` and `DocumentReference:read`.
**Scope:** The caller's project (from the token). Only documents your access policy lets you read are returned.

## Request

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `_count` | `integer` | No | Page size. Default `100`. The FHIR server reduces a value above `1000` to `1000`. |
| `_offset` | `integer` | No | Number of documents to skip. Default `0`. The FHIR server rejects a value above `10000`. |
| `_sort` | `string` | No | Sort order. Default `-_lastUpdated`, newest first. Use a [`DocumentReference`](/api/fhir/r4/document-reference) search parameter name, with a leading `-` for descending. Separate several with commas. |

## Behaviour

- The search covers every [`DocumentReference`](/api/fhir/r4/document-reference) you can read, including documents that were not created through these routes. There are no other filters.
- Page with `_offset` and `_count`: ask for the next page with `_offset` raised by `_count`. You are at the end when `resources` has fewer entries than `_count`. Offsets above `10000` are refused, so sort in the other direction to reach the other end of a long list.
- `total` is an estimate of the number of matching documents. It is exact for small result sets. Use it for a page counter, not for logic that needs the exact number.
- Each entry has `id`, `meta.lastUpdated`, `author`, `fileName`, `contentType` and, when the document is public, `publicToken`. `author` is the first author of the document. A document with no attachment has no `fileName` or `contentType`. Entries never include `uploadOptions`.
- Anyone who can read a public document can see its `publicToken`.
- Ovok does not validate `_count` and `_offset` beyond reading them as integers. Send whole numbers.

## Example

```bash
curl -G 'https://api.sandbox.ovok.com/document' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -d '_count=20' \
  -d '_offset=0' \
  -d '_sort=-_lastUpdated'
```

## Successful response

`200` — A page of documents and the estimated total.

```json
{
  "total": 2,
  "resources": [
    {
      "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
      "meta": { "lastUpdated": "2026-10-09T09:20:05.112Z" },
      "author": {
        "reference": "Practitioner/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
        "display": "Alex Lee"
      },
      "fileName": "new-cat.png",
      "contentType": "image/png",
      "publicToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcmVuY2UiOiJEb2N1bWVudFJlZmVyZW5jZS8zZjFjMmI3ZS04ZDRhLTRjMWUtOWIyZi02YTdkNWU0YzNiMjEiLCJpYXQiOjE3OTE1MDAwMDB9.c2lnbmF0dXJl"
    },
    {
      "id": "5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02",
      "meta": { "lastUpdated": "2026-10-08T14:03:51.870Z" },
      "author": {
        "reference": "Practitioner/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
        "display": "Alex Lee"
      },
      "fileName": "report.pdf",
      "contentType": "application/pdf"
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | Estimated number of matching documents, across all pages. |
| `resources` | `object[]` | The documents of this page. Empty when there are none. |
| `resources[].id` | `string (uuid)` | Document id. |
| `resources[].meta.lastUpdated` | `string` | When the document last changed. ISO 8601. |
| `resources[].author` | `object` | First author of the document. Left out when it has none. |
| `resources[].author.reference` | `string` | Author reference, for example `Practitioner/<id>`. |
| `resources[].author.display` | `string` | Author display name. Left out when not set. |
| `resources[].fileName` | `string` | Attachment title. Left out when not set. |
| `resources[].contentType` | `string` | Attachment content type. Left out when not set. |
| `resources[].publicToken` | `string` | Public token. Left out unless the document is public. |

## Errors

| Status | Meaning |
| --- | --- |
| `400` | The FHIR server rejects the search: `_sort` names an unknown search parameter, or `_offset` is above `10000`. |
| `401` | Bearer token is missing, invalid or revoked. |
| `403` | Your access policy does not allow searching `DocumentReference`. |
| `429` | You exceeded the rate limit for your user type. |