REST API Reference

Dyrected derives a REST API from collections and globals in dyrected.config.ts. Runtime OpenAPI is project-specific; the generated inventory below uses a representative maximal configuration to cover every route family.

Base URL

Self-hosted routes are normally exposed beneath the application origin:

https://example.com/api

SDK configuration takes the origin before /api, because SDK methods add /api themselves.

Authentication

Depending on access configuration, requests use a site API key, a user JWT, and—in Cloud mode—a site identifier.

An endpoint can be public when its access rule allows the operation. The representative table's authentication column reflects the fixture, not a guarantee about your project.

Listing and filtering

Collection list routes accept limit, page, sort, depth, and a JSON-encoded where object.

const query = new URLSearchParams({
  limit: '10',
  sort: '-createdAt',
  depth: '1',
  where: JSON.stringify({ status: { equals: 'published' } }),
})

const response = await fetch(`/api/collections/posts?${query}`)

Operators include equals, not_equals, contains, starts_with, in, not_in, gt, gte, lt, lte, and exists. Incoming filters are sanitized against the configured schema; fields with admin.filterable: false cannot be used for filtering.

List responses use the shared pagination envelope:

{
  "docs": [],
  "total": 0,
  "limit": 10,
  "page": 1,
  "totalPages": 0,
  "hasNextPage": false,
  "hasPrevPage": false
}

Collections

• GET /api/collections/{slug} lists documents.
• POST /api/collections/{slug} creates a document or upload.
• GET /api/collections/{slug}/{id} reads one document.
• PATCH /api/collections/{slug}/{id} performs a partial update.
• DELETE /api/collections/{slug}/{id} deletes one document.
• DELETE /api/collections/{slug}/delete-many deletes authorized IDs in bulk.
• POST /api/collections/{slug}/seed initializes configured seed content.

Access rules, hooks, field validation, relationship depth, and workflows apply at this boundary.

Uploads and media

Upload collections accept multipart/form-data with a required file part and optional configured metadata fields.

curl -X POST https://example.com/api/collections/media \
  -H "Authorization: Bearer $DYRECTED_TOKEN" \
  -F "[email protected]" \
  -F "alt=Mountain at sunrise"

Use URLs returned by the API. Local storage can serve bytes through /api/media/{filename}; cloud adapters normally return provider/CDN URLs.

Globals

GET /api/globals/{slug} reads a singleton and PATCH /api/globals/{slug} updates it. Global access and hooks run in the same way as their configured operations.

Authentication routes

Auth-enabled collections add login, logout, current-user, refresh, invitation, initialization, first-user, password reset, and password-change routes. Consult runtime OpenAPI for exact request and response schemas because the collection slug and document fields are project-specific.

Workflows

Workflow-enabled collections add an atomic transition route and paginated workflow history. Supply expectedRevision when the client must reject stale transitions, and include comments when required by the configured transition.

Schemas, preferences, preview, and dynamic options

• /api/schemas serializes current collection/global schemas.
• /api/preferences/{key} stores authenticated user preferences.
• /api/preview-token creates a signed preview credential; /api/preview-data resolves it.
• /api/dyrected/options/{collection}/{field} resolves server-side dynamic options.

Preview tokens and schema responses can expose application structure. Apply appropriate transport security and avoid logging secrets.

Error responses

Use HTTP status codes as the primary error category and display server validation messages safely. Common cases include invalid input (400), missing credentials (401), denied access (403), missing resources (404), conflicts (409), oversized uploads (413), and unexpected server failures (500).

Clients should not retry validation or authorization failures blindly. Retry transient failures only when the operation is idempotent or has an application-level idempotency strategy.

Generated endpoint inventory