Search documents

Method	Path
GET	/document

Authentication · Access policies · 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 search parameter name, with a leading - for descending. Separate several with commas.

Behaviour

• The search covers every DocumentReference 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

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.

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