Plattform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Modelle Tools & Services
Lösungen
Organisationen Entwickler Internet Service Provider Managed Service Provider AI-in-a-Box
Ressourcen
Support Documentation Blog Downloads
Unternehmen
Über uns Forschung Karriere Investieren Kontakt
Anmelden

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#

json
1
2
3
4
5
6
7
8
{
  "slug": "scaidial",
  "name": "ScaiDial",
  "description": "ScaiDial — outbound notification dispatch.",
  "visibility": "public",
  "parent_namespace_id": "<uuid-or-null>",
  "theme": {"primary": "#…"}
}

?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_id is 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.

bash
1
2
3
4
5
curl -X POST "$BASE/api/v1/docs/_namespaces?bootstrap=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Site-ID: $SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{"slug":"scaidial","name":"ScaiDial","visibility":"public"}'

Response (201) gains a bootstrap sub-object:

json
1
2
3
4
5
6
7
8
9
{
  "id": "…", "slug": "scaidial", "default_version_id": "…",
  "bootstrap": {
    "version_id": "…",
    "version_slug": "v1",
    "mount_id": "…",
    "mount_path": "/docs/scaidial"
  }
}

?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:

json
1
2
3
4
5
6
7
8
{
  "extended_scopes": {
    "<api-key-uuid>": [
      "docs:read:scaidial", "docs:write:scaidial", "docs:manage:scaidial",
      "downloads:read:scaidial", "downloads:write:scaidial", "downloads:delete:scaidial"
    ]
  }
}

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:

bash
1
2
3
4
5
curl -X POST "$BASE/api/v1/docs/_namespaces?bootstrap=true&extend_group_scopes=true" \
  -H "Authorization: Bearer $GROUP_API_KEY" \
  -H "X-Site-ID: $SITE_ID" \
  -H "Content-Type: application/json" \
  -d '{"slug":"scaidial","name":"ScaiDial","description":"…","visibility":"public"}'

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:

bash
1
2
3
4
curl -X PATCH "$BASE/api/v1/docs/scaidial" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"coming_soon": false}'

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_order sets the sidebar order. Pass an integer on every PUT; without it siblings sort alphabetically.
  • Create parents first. Writing concepts/foo before concepts exists returns 400 Parent path 'concepts' does not exist.
  • DELETE archives. The page leaves the public site but stays in the tree with status: archived.
  • A page may not be readable for a few tens of milliseconds after its PUT returns 200. 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.
Updated 2026-11-15 01:58:03 View source (.md) rev 2