Collections, globals, and files

Use Ridu’s collection, global, trash, version, publishing, scheduling, and upload routes.

Collection routes use the authored collection slug as {collection} and the public document ID as {id}. Ridu only exposes routes supported by that resource’s configuration.

Read and write collections

GET /api/collections/{collection}: List access-checked documents.
POST /api/collections/{collection}: Create an ordinary JSON document or upload document.
GET /api/collections/{collection}/{id}: Read one document.
PATCH /api/collections/{collection}/{id}: Update one document; accepts If-Match.
DELETE /api/collections/{collection}/{id}: Delete one document or move it to trash when enabled.
GET /api/collections/{collection}/count: Count documents with the same filter, locale, and trash context as list.
POST /api/collections/{collection}/{id}/duplicate: Duplicate an ordinary document with optional field overrides.
POST /api/collections/{collection}/{id}/copy-locale: Copy localized values with { "from": "en", "to": "fr" }; accepts If-Match.
PATCH /api/collections/{collection}/{id}/joins/{field}: Add or remove targets from a writable inverse join.

An auth collection creates users through /api/auth/{collection}/create-user; its ordinary collection POST route is unavailable. An upload collection accepts multipart input on its collection POST route. See the relevant sections below before choosing a request body.

If-Match accepts a quoted or unquoted positive revision. Use the last revision read by the client; Ridu returns a conflict instead of silently replacing a newer edit.

To inspect one saved collection document or global in the admin, open its API tab. It shows the current GET URL and response; change the content locale, relationship depth, or authenticated setting to rerun the read. The tab reads stored data, so unsaved form changes are not part of its response. Copy the URL, or for a collection open API reference for list, read, create, update, and delete examples in TypeScript, cURL, and Go. The generated OpenAPI file remains the exact route contract.

Run one action for several documents

Send POST /api/collections/{collection}/bulk with 1–100 unique, non-empty IDs:

request.json

{
  "action": "update",
  "ids": ["post-1", "post-2"],
  "data": {
    "status": "archived"
  }
}

`action`	Required input and result
`update`	Requires `data`; updates every admitted document.
`publish`	Publishes every admitted versioned document.
`unpublish`	Returns every admitted versioned document to draft.
`delete`	Deletes or trashes every admitted document.
`restoreDeleted`	Restores every admitted trashed document.
`deletePermanent`	Permanently deletes every admitted document.

Capability and access checks run for each document. A bulk request groups work; it does not bypass authorization or validation.

Work with trash

These routes exist only for a trash-enabled collection:

GET /api/collections/{collection}?trash=true: List only trashed documents.
POST /api/collections/{collection}/{id}/restore-deleted: Restore one document.
DELETE /api/collections/{collection}/{id}/permanent: Permanently delete one document.
DELETE /api/collections/{collection}/trash: Permanently empty this collection’s trash.

See Bulk operations and trash for UI behavior, retention, and irreversible deletion rules.

Publish, schedule, and restore versions

These routes exist only when collection versions are enabled. Unpublish, including a scheduled unpublish action, additionally requires draft support. Publish, unpublish, restore, and schedule operations accept If-Match.

For draft-enabled resources, ?draft=true selects authorized working content on reads and saves pending content on create/update. ?draft=false selects the preserved live snapshot on reads; on create it validates and publishes atomically. To publish an existing working draft, use the publish route. Draft writes defer editorial completeness, not structural validation or access. Live filters, counts, sorting, and pagination use the live snapshot’s values.

GET /api/collections/{collection}/{id}/versions: List stored snapshots.
GET /api/collections/{collection}/{id}/versions/{revision}: Read one positive integer revision.
POST /api/collections/{collection}/{id}/publish: Publish the current document.
POST /api/collections/{collection}/{id}/unpublish: Remove the live snapshot while retaining working content.
POST /api/collections/{collection}/{id}/discard-draft: Reset saved pending changes to the live snapshot without unpublishing. Requires draft support and update access.
POST /api/collections/{collection}/{id}/restore/{revision}: Restore a snapshot and its publication state; add ?draft=true to restore working content without changing the live snapshot.
GET /api/collections/{collection}/{id}/schedule: List scheduled publication jobs.
POST /api/collections/{collection}/{id}/schedule: Schedule a change with required action (publish or unpublish) and RFC 3339 runAt fields.
DELETE /api/collections/{collection}/{id}/schedule/{jobId}: Cancel a scheduled publication.

For example, schedule a publish at a known instant and retain the editor’s display timezone:

http

POST /api/collections/posts/post-1/schedule
Content-Type: application/json
If-Match: "7"

{"action":"publish","runAt":"2027-01-02T09:00:00Z","timeZone":"Europe/London"}

runAt must include an RFC 3339 offset; timeZone is optional and only affects how the event is displayed. It accepts UTC, a ±HH:mm offset, or an IANA region such as Europe/London. A successful schedule returns 201 with scheduledPublication, including its id, action, documentId, expectedRevision, runAt, and optional timeZone. The GET route returns scheduledPublications for queued and failed jobs. To schedule an unpublish, use "action":"unpublish" on a currently published draft-capable document.

See Drafts and versions for the status model and scheduling lifecycle.

Upload and serve files

An upload-enabled collection adds these routes:

POST /api/collections/{collection}: Multipart file, with optional JSON data and image fields. For a draft-enabled collection, ?draft=false validates and publishes on creation.
POST /api/collections/{collection}/remote-upload: JSON url, optional data, image, and filename. Creates a document; ?draft=false validates and publishes on creation.
POST /api/collections/{collection}/upload-preview: JSON url and optional id; returns a remote file for inspection without saving it.
PATCH /api/collections/{collection}/{id}/upload: Replace the file with multipart input, or send JSON to update metadata/image; accepts If-Match.
GET /api/collections/{collection}/{id}/upload-source: Read the immutable original file through editor access.
HEAD /api/collections/{collection}/{id}/upload-source: Read original-file metadata without the body.
GET /api/uploads/{collection}/{object-key}: Return an access-checked stored object body.
HEAD /api/uploads/{collection}/{object-key}: Return the same object metadata without the body.

Multipart upload and file replacement require file. The optional data and image multipart fields contain JSON objects. Creation uses ?draft=false to validate and publish; an existing asset update uses publish=true to commit file/metadata changes and publication in one operation. JSON updates can change data or image without replacing the file. Multipart requests are limited to the collection’s maximum file size plus framing allowance. Remote-host, redirect, MIME, image-dimension, spool, and storage rules come from the upload configuration. Object responses are private and non-cacheable; HTML, SVG, and XML-like active content is forced to download with a sandbox policy. See Uploads for complete examples and limits.

Read and update globals

GET /api/globals/{global}: Read the access-checked global.
PATCH /api/globals/{global}: Update the global; accepts If-Match.
POST /api/globals/{global}/copy-locale: Copy localized values; accepts If-Match.
GET /api/globals/{global}/versions: List global versions.
GET /api/globals/{global}/versions/{revision}: Read one global revision.
POST /api/globals/{global}/publish: Publish a versioned global.
POST /api/globals/{global}/unpublish: Return a versioned global to draft.
POST /api/globals/{global}/restore/{revision}: Restore a global revision; accepts If-Match.

Version routes are absent when the global does not enable versions. Global scheduled publishing is not implemented.

Inspect schema and process health

GET /api/schema: Read the canonical public manifest envelope used by clients and the admin.
GET /healthz: Check process liveness.
GET /readyz: Check configured dependencies and migration readiness.

The public manifest describes fields and capabilities; it never contains executable access rules or secrets. For exact request and response schemas, inspect generated/ridu.openapi.json.