Overview

View as Markdown

Official documentation of the Modular DS Public API v1 ({{base_url}}/api/public/v1).

Authentication: personal access tokens. Create one from the dashboard: the token is bound to your membership in one organization and acts with your role inside it. Send it as Authorization: Bearer <token> — set the public_token variable in your environment. Read-only tokens (read ability) can only perform GET requests; mutating methods answer 403. Session cookies never authenticate this surface.

Format (JSON:API 1.1):

  • Send Accept: application/vnd.api+json (the server pins it anyway — every response, including errors, is a JSON:API document).
  • Filtering: filter[name]=value / filter[name][]=v1. Unknown filters → 400; invalid values → 422. Boolean query params use 1/0.
  • Sorting: sort=field,-other (leading - = descending). Includes: include=rel1,rel2. Sparse fieldsets: fields[sites]=name,host.
  • Pagination: page[number], page[size] (max 50).
  • Errors: {errors: [{status, title, detail, source}], jsonapi}. Ids are strings; types kebab-case plural.

Writes are semantic REST: create answers 201 with the resource document and a Location header; update answers 200 with the document; delete answers 204.

Limits: 120 requests/min per token. Resources of other organizations answer 404.

Secrets: no credential value ever travels in an ordinary response — the manual connection flow uses a short-lived signed reveal URL and the plugin flow a presigned download URL.