JSON:API routes

Updated Oct 24, 2026 v0.0.1

Mishka Document serves its records over JSON:API. Readers use a small public set of routes, and site and master admins use full create, read, update and archive routes. This reference lists the routes of each surface, who can call them, and the type each one returns. The CMS mounts the API at /api/json, so every path below starts with /api/json.

Surfaces and access

Surface	Path prefix	Who calls it
Master admin	`/v1/master/admin/mishka-document/<resource>`	A master account. It works across sites and needs `admin:api:document:workspace` or `admin:api:document:section`, whichever the resource asks for.
Tenant admin	`/v1/tenant/admin/mishka-document/<resource>`	A site account holding the same names for its own site.
Reader	`/v1/user/mishka-document/<resource>`	Any reader. Lists and single reads need no sign-in. Following and bookmarking need one.

The site comes from the host of the request. A request that names no site, such as one with the header x-no-tenant, is answered 400 with the code tenant_required on the reader routes.
Sign in at POST /api/json/v1/auth/user/sign-in with a user body holding email and password. The answer carries the token in meta.token. Send it as a bearer token. A master account adds the header x-no-tenant: true when it signs in.
Reader reads leave out locked records the caller cannot open. A locked record asked for by id answers 404 with the code not_found, the same as an id nothing is stored at. See Review, status and who can read a page.
Lists use offset pagination, 20 records by default and 100 at most. The comment lists of an issue and of a contributor, and the master list of issue comments, return 50 by default and 200 at most.
A write body is a JSON:API document: {"data": {"type": "<type>", "attributes": {}}}.

Resource types

Resource path	Type	Area
`workspace`	`workspace`	Workspace
`workspace-version`	`workspace_version`	Workspace
`workspace-version-lineage`	`workspace_version_lineage`	Workspace
`section`	`section`	Section
`note`	`note`	Section
`section-draft`	`section_draft`	Section
`note-draft`	`note_draft`	Section
`tag`	`tag`	Section
`issue`	`issue`	Section
`issue-comment`	`issue_comment`	Section
`workspace-follow`	`workspace_follower`	Reader
`section-bookmark`	`section_bookmark`	Reader

Admin routes with the same shape

The resources workspace, section, note, section-draft, note-draft, tag, issue and issue-comment share these routes on both admin surfaces. A delete archives the record. The permanent delete is a separate route.

Method and path	Does
`GET /`	Lists records.
`GET /:id`	Reads one record.
`GET /archived`	Lists archived records.
`GET /archived/:id`	Reads one archived record.
`POST /`	Creates a record.
`PATCH /:id`	Updates a record.
`PATCH /:id/unarchive`	Restores an archived record.
`DELETE /:id/archive`	Archives a record.
`DELETE /:id/permanent`	Deletes a record for good.

Admin routes that differ

Resource	Method and path	Surface	Does
`workspace`	`GET /language-variants`	Both	Lists the translations of a document, given a language group.
`workspace-version`	`GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`	Both	The usual routes. A delete removes the version for good.
`workspace-version`	`GET /workspace/:workspace_id`	Both	Lists the versions of one document.
`workspace-version`	`GET /latest`	Tenant	Lists the versions marked latest.
`workspace-version`	`GET /status/:status`	Tenant	Lists the versions with one status.
`workspace-version`	`PATCH /:id/publish`	Tenant	Sets the status to stable and publishes it now.
`workspace-version`	`PATCH /:id/mark-latest`	Tenant	Marks the version as the document's latest.
`workspace-version-lineage`	`GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`	Both	The clone records. A delete removes the record for good.
`workspace-version-lineage`	`GET /new-version/:new_version_id`, `GET /source-version/:source_version_id`, `GET /date-range`, `GET /recent`	Both	Finds clone records by the new version, the source version, a date range, or the most recent.
`issue`	`PATCH /:id/mark-in-progress`, `/mark-resolved`, `/mark-closed`, `/reopen`	Tenant	Moves the issue to a status.
`issue-comment`	`GET /by-issue/:issue_id`, `GET /by-contributor/:contributor_id`	Tenant	Lists the comments of an issue, or of a contributor.

Reader routes

Method and path under `/v1/user/mishka-document`	Does	Sign-in
`GET /workspace`, `GET /workspace/:id`	Lists active documents, or reads one.	No
`GET /workspace-version`, `GET /workspace-version/:id`	Lists versions that are Alpha, Beta, Rc or Stable, or reads one.	No
`GET /workspace-version-lineage/:id`, `/new-version/:new_version_id`, `/source-version/:source_version_id`, `/recent`	Reads clone records.	No
`GET /section`, `GET /section/:id`	Lists approved pages, or reads one.	No
`GET /section/workspace/:workspace_version_id/version/:version_number`	Lists the approved pages of one version.	No
`GET /tag`, `GET /tag/:id`	Lists tags, or reads one.	No
`GET /workspace-follow/my-following`	Lists the documents the caller follows.	Yes
`POST /workspace-follow`	Follows a document. Attribute `workspace_id`, optionally `notification_enabled`.	Yes
`PATCH /workspace-follow/:id`	Changes `notification_enabled`.	Yes
`DELETE /workspace-follow/:id`	Unfollows.	Yes
`GET /section-bookmark/my-bookmarks`	Lists the caller's bookmarks of approved pages.	Yes
`POST /section-bookmark`	Bookmarks a page. Attribute `section_id`.	Yes
`DELETE /section-bookmark/:id`	Removes a bookmark.	Yes

Example: create a document as a master

json

{
  "data": {
    "type": "workspace",
    "attributes": {
      "name": "Tech Workspace",
      "slug": "tech-workspace",
      "description": "Technology documentation",
      "status": "active",
      "language": "en",
      "site_id": "<site id>"
    }
  }
}

Send it with POST /api/json/v1/master/admin/mishka-document/workspace. A site account sends the same body to the tenant path and leaves out site_id.