Docs API
Endpoints under /api/v1/docs/* for managing namespaces, versions, pages,
mounts, and search. Authentication: JWT (superuser) or an API key with the
docs.manage permission slug (see API keys).
For the full conceptual model, see Docs subsystem.
POST /api/v1/docs/_namespaces#
Create a doc namespace. By default this just inserts a doc_namespaces row —
no version, no mount. Two query flags let you fold setup into a single call.
Body#
1 2 3 4 5 6 7 8 | |
?bootstrap=true — one-shot namespace + v1 + mount#
Atomically creates the namespace, a default v1 version
(status=published, is_default=1), and a site_doc_mounts row on the
site identified by the X-Site-ID header.
- Top-level namespace → mount path
/docs/<slug> - Sub-product (when
parent_namespace_idis set) →/docs/<parent_slug>/<slug>
Requires X-Site-ID. If the resolved mount path is already in use on the
site, the call is rejected with 409 — nothing is partially created.
1 2 3 4 5 | |
Response (201) gains a bootstrap sub-object:
1 2 3 4 5 6 7 8 9 | |
?extend_group_scopes=true — auto-grant scopes to issuing key's group#
Appends the six docs/downloads scopes for the new slug
(docs:{read,write,manage}:<slug>, downloads:{read,write,delete}:<slug>)
to every active API key in the caller's group. Idempotent — keys that
already carry a scope are left unchanged. Every mutated key gets an
api_key_scope_audits row recording the addition with
reason=bootstrap_extend:<slug>.
Constraints:
- Caller must authenticate with an API key (JWTs cannot use this flag).
- That API key must be group-bound (
group_id IS NOT NULL). User-bound keys cannot self-extend.
Response gains an extended_scopes map keyed by api_key_id:
1 2 3 4 5 6 7 8 | |
If no keys needed extending (everyone already had the scopes), the map is present but empty.
Combining the flags#
The typical "create a sub-product end-to-end" call uses both:
1 2 3 4 5 | |
One round-trip yields the namespace, its published v1, the mount on the
site, and the scopes propagated across the issuing group's fleet of keys.
Error codes#
| Code | HTTP | Meaning |
|---|---|---|
BOOTSTRAP_REQUIRES_SITE |
400 | ?bootstrap=true was sent without X-Site-ID. |
EXTEND_REQUIRES_API_KEY |
400 | ?extend_group_scopes=true was sent on a JWT request. |
EXTEND_REQUIRES_GROUP_KEY |
400 | Caller's API key is user-bound, not group-bound. |
| — | 409 | Resolved mount path already exists on this site, or the slug is taken. detail is a plain message. |
PATCH /api/v1/docs/{ns}#
Update namespace settings: name, description, visibility,
read_role_slugs, parent_namespace_id, theme, default_version_id and
coming_soon. Requires docs:manage:<ns>.
coming_soon: true makes the public see a "Coming Soon" teaser for every URL
under the mount, and marks the product "soon" on the hub. Superusers still
see the real pages. Set it back to false when the docs are ready:
1 2 3 4 | |
All routes#
All under /api/v1/docs.
| Method | Path | Purpose |
|---|---|---|
GET |
/_namespaces |
Namespaces visible to the caller |
POST |
/_namespaces |
Create a namespace (flags above) |
GET PATCH DELETE |
/{ns} |
Read, update, delete a namespace |
GET POST |
/{ns}/_versions |
List, create versions |
POST |
/{ns}/_versions/_fork |
Copy a version into a new one |
PATCH DELETE |
/{ns}/_versions/{ver} |
Update, delete a version |
GET |
/{ns}/{ver}/_tree |
Page tree |
GET PUT DELETE |
/{ns}/{ver}/{path} |
Read, upsert, delete a page |
POST |
/_search |
Hybrid search; filter by namespace, version, path_prefix in the body |
GET POST |
/_mounts/{site_id} |
List, create mounts on a site |
DELETE |
/_mounts/{mount_id} |
Remove a mount |
GET |
/_index/status |
Search index status |
POST |
/_index/reindex, /_index/reset |
Rebuild the search index |
Page writes:
sort_ordersets the sidebar order. Pass an integer on everyPUT; without it siblings sort alphabetically.- Create parents first. Writing
concepts/foobeforeconceptsexists returns400 Parent path 'concepts' does not exist. DELETEarchives. The page leaves the public site but stays in the tree withstatus: archived.- A page may not be readable for a few tens of milliseconds after its
PUTreturns200. A script that writes a parent and then immediately its first child can get the parent error above. Wait about 50 ms, or retry that error once.