REST API

Ridu generates an OpenAPI document from the resolved application manifest. The tables below are the framework route families; your generated/ridu.openapi.json is authoritative for the concrete collection, global, auth, upload, version, and plugin routes enabled by your config.

A browser frontend on another origin must configure the HTTP boundary before calling these routes. See CORS for exact origins, credentials, custom headers, proxy trust, and preflight errors. Server-to-server clients do not need CORS.

Collection routes

{collection} is the authored collection slug and {id} is the public document ID.

Bulk action is exactly one of update, publish, unpublish, delete, restoreDeleted, or deletePermanent. data is required only by update. Capability and access checks still run per document; this route is not a permission bypass.

Trash

These routes exist only for a trash-enabled collection:

Versions and scheduling

These routes exist only when collection versions are enabled; draft/publish actions additionally depend on the configured version capability.

Publishing, unpublishing, restoring, and scheduling accept If-Match for optimistic concurrency.

Uploads

Upload-enabled collections add these transports:

Multipart requests are limited to the collection’s maximum file size plus framing allowance. Remote-host, redirect, MIME, image-dimension, spool, and storage policies come from the configured upload backend. Object responses are always private and non-cacheable; HTML, SVG, and XML-like active content is forced to download with a sandbox policy.

Globals and schema

Global scheduled publishing is not implemented. Version routes are absent when versions are not configured.

Authentication and account routes

Auth-collection feature flags determine which routes are generated.

Login establishes the HttpOnly, SameSite=Lax ridu_session cookie. Cookie-authenticated browser requests must include credentials. A raw session token uses Authorization: Session <token>; Authorization: JWT <token> remains accepted for compatibility. An API key uses Authorization: Bearer <key>. API-key creation specifically requires cookie authentication, and the returned secret cannot be retrieved from a later list call.

Access, preferences, and document locks

Capability responses help build interfaces. Every later operation independently re-runs access rules and storage predicates, so a cached capability response is never authorization.

Preview routes

Preview tokens are resource-bound credentials, not general API keys. See Live preview for iframe URL and update-channel handling.

Plugin routes

Application-authored root, collection, and global routes appear in the same generated OpenAPI document. Their handlers own arbitrary request and response shapes, and they are not authenticated automatically. See Custom endpoints for mounting, path parameters, actor/LocalAPI context, limits, route precedence, and raw SDK calls.

Compiled plugins contribute concrete method/path pairs to the generated OpenAPI document. Generic namespaced endpoints use /api/plugins/{plugin-key}/{endpoint}; a plugin transport may instead declare its exact path, such as the official GraphQL transport. Only declared methods are accepted, request bodies are bounded, and plugin errors use the same Ridu envelope. Inspect your generated OpenAPI file and the installed plugin’s reference module, such as graphql, for its available routes.

Query-string encoding

Collection list and count routes reject unknown query parameters.

const query = new URLSearchParams({
  page: '1',
  limit: '20',
  where: JSON.stringify({ status: { equals: 'published' } }),
  select: JSON.stringify({ title: true, author: true }),
  locale: 'fr',
  'fallback-locale': 'en'
});
query.append('sort', '-createdAt');
query.append('sort', 'title');

const response = await fetch(`${origin}/api/collections/posts?${query}`, {
  credentials: 'include'
});

Exact operators and resource paths come from the generated contract; see Querying data.

Requests, responses, and limits

JSON input is strict: request objects reject unknown fields, duplicate keys, trailing data, excessive structural complexity, and bodies over the configured server limit (1 MiB by default). Send Content-Type: application/json for JSON and multipart/form-data for direct uploads. Successful resource reads use Ridu envelopes such as { "doc": … }, { "docs": …, "pagination": … }, or capability-specific envelopes. 204 is not the generic delete shape; delete operations return a JSON { id, deleted: true } envelope.

Every response includes X-Request-ID; include it when reporting a failure. CORS permits Accept, Authorization, Content-Type, and If-Match by default when an origin is allowed. If-Match accepts a quoted or unquoted positive revision. Host allowlists, CORS, rate limits, request timeouts, upload admission, and plugin-specific body limits may reject a request before its handler runs.

Errors

Failures use one stable JSON envelope. Validation errors use HTTP 422 and put field-addressable problems in issues; conflicts use HTTP 409. Do not branch on message text.

{
  "error": {
    "code": "validation",
    "status": 422,
    "message": "document validation failed",
    "requestId": "req_…",
    "issues": [{ "code": "required", "path": "title", "message": "title is required" }]
  }
}

The generated OpenAPI file is the language-neutral authority for enabled paths and schemas. The protocol reference lists the shared envelopes and stable error-code union; the SDK reference lists the typed Fetch methods. Prefer the TypeScript SDK when TypeScript is available—it performs query encoding and success-envelope checks for you.