OVOK DOCS
Get startedOvokSignalsSDKsGuidesAPI referenceDeveloper resources
Payload CMS Public Delivery

List published documents of a public collection

  • Sandbox: available
  • Staging: available
  • Production: unknown
GET
/v1/public/cms/collections/{collectionSlug}/items

Lists the published documents of a CMS collection for one tenant, in one language, one page at a time. Use it to show content such as release notes or articles in an app or website.

Auth: one of the following, checked in this order:

  • The CMS public API key, in the x-api-key header, as Authorization: Bearer <key>, or as the apiKey query parameter.
  • No key, for collections configured as keyless (by default legal-pages and translations).
  • A signed-in Ovok session (bearer token), which may only read its own tenant.

Scope: the tenant you name, by tenant code (x-ovok-tenant-code header or tenant query parameter) or by project id (x-ovok-medplum-project-id header or projectId query parameter). Headers win over query parameters, and a tenant code wins over a project id. If you name neither, a signed-in session reads its own tenant. Each Ovok deployment has one set of content; there is no environment to choose.

Behaviour

  • Any collection except the users and tenants system collections can be read.
  • Only documents with status published are returned. The response is the CMS list envelope (docs, totalDocs, page, limit, and so on).
  • locale is a language tag such as de or en-US. Without it, the CMS default locale is used. Missing translations fall back as configured in the CMS.
  • page defaults to 1 and is limited to 1 to 100. limit defaults to 20 and is limited to 1 to 50. Values outside those ranges are clamped; values that are not whole numbers fall back to the default.
  • sort is a top-level field name, optionally prefixed with - for descending order, for example -publishedAt. Without it, the CMS default order is used.
  • Ovok also has a shared tenant whose published documents are added to every tenant's list. Where both have a document with the same slug, the tenant's own document wins. If either tenant has more than 200 published documents in the collection, only the tenant's own documents are returned.
  • Responses are cached by Ovok for up to 60 seconds. A request that names a tenant gets Cache-Control: public, s-maxage=60, stale-while-revalidate=300 and a Vary on the tenant and API key headers. A request that names no tenant gets Cache-Control: no-store. Error responses carry neither.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/public/cms/collections/release-notes/items?tenant=my-medical-project&locale=de&sort=-publishedAt&limit=10' \  -H 'x-api-key: <cms public api key>'

Authorization

api-key
headerx-api-key<token>

Path Parameters

collectionSlug*string

Slug of a collection (any but users and tenants), e.g. "release-notes".

Query Parameters

page?number

1-based page number. Defaults to 1.

limit?number

Items per page. Defaults to 20, capped at 50.

sort?string

Payload sort expression: a field name, optionally prefixed with "-" for descending (e.g. "-publishedAt"). Omit for the CMS default order.

tenant?unknown

Tenant code identifying the project (alternative to the x-ovok-tenant-code header).

locale?string

Response language as a language tag (e.g. "de", "en-US"). Omit for the CMS default locale; missing translations fall back per the CMS localization config. Malformed tags are rejected with 400.

Response Body

Paginated published documents (Payload list envelope).

application/json
  1. response
docs*array<>
totalDocs*number
limit*number
totalPages*number
page*number
pagingCounter*number
hasPrevPage*boolean
hasNextPage*boolean
prevPage*number
nextPage*number
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/public/cms/collections/string/items'
Example Response
{  "docs": [    {      "property1": null,      "property2": null    }  ],  "totalDocs": 0,  "limit": 0,  "totalPages": 0,  "page": 0,  "pagingCounter": 0,  "hasPrevPage": true,  "hasNextPage": true,  "prevPage": 0,  "nextPage": 0}

Revoke a CMS API key DELETE

Revokes one of your current project's CMS API keys. Public delivery stops taking it at once. **Auth:** bearer token of a project admin. The caller must also be a Practitioner, an admin or hold the System Owner access policy. **Scope:** the caller's project (from the token). ## Behaviour - `id` is a key's `id` from `GET /v1/cms/api-keys`; `default` revokes the default key. - A key the project does not hold returns 404 `CMS_API_KEY_NOT_FOUND`. - A 409 means the project changed while the server wrote. Retry. - Public responses a CDN already cached may still be served for up to a minute. - The answer is 204. ## Example ```bash curl -X DELETE 'https://api.sandbox.ovok.com/v1/cms/api-keys/default' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ```

Get a published document by slug GET

Returns one published document of a CMS collection by its slug. Use it for stable public pages and deep links, such as terms and conditions or a privacy policy. **Auth:** one of the following, checked in this order: - The CMS public API key, in the `x-api-key` header, as `Authorization: Bearer <key>`, or as the `apiKey` query parameter. - No key, for collections configured as keyless (by default `legal-pages` and `translations`). - A signed-in Ovok session (bearer token), which may only read its own tenant. **Scope:** the tenant you name, by tenant code (`x-ovok-tenant-code` header or `tenant` query parameter) or by project id (`x-ovok-medplum-project-id` header or `projectId` query parameter). Headers win over query parameters, and a tenant code wins over a project id. If you name neither, a signed-in session reads its own tenant. Each Ovok deployment has one set of content; there is no environment to choose. ## Behaviour - Any collection except the `users` and `tenants` system collections can be read. - Only a document with status `published` is returned. The response is the document itself, with the fields its collection defines. - `slug` must start with a lowercase letter or digit and contain only lowercase letters, digits, `-`, `_` and `.`, up to 128 characters. - `locale` is a language tag such as `de` or `en-US`. Without it, the CMS default locale is used. Missing translations fall back as configured in the CMS. - If the tenant has no published document with this slug, Ovok returns the shared tenant's document with that slug, when one exists. - Responses are cached by Ovok for up to 60 seconds. A request that names a tenant gets `Cache-Control: public, s-maxage=60, stale-while-revalidate=300` and a `Vary` on the tenant and API key headers. A request that names no tenant gets `Cache-Control: no-store`. Error responses carry neither. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/public/cms/collections/legal-pages/items/terms-and-conditions?tenant=my-medical-project&locale=en-US' ```