Integrator Guide¶

This guide is for scripts, CI/CD pipelines, and other programmatic consumers of the Docroot REST API.

Authentication¶

Client-credentials grant¶

Use the OAuth 2.0 client-credentials grant to obtain a token without user interaction.

TOKEN=$(curl -s -X POST \
  "https://idp.example.com/realms/myrealm/\
protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id=my-ci-client \
  -d client_secret=MY_SECRET \
  | jq -r .access_token)

Setting up for unattended uploads¶

Before an unattended pipeline can upload, a human operator must do the following once:

Create the namespace (via the UI or API with a human token).
In the namespace ACL, add the confidential client’s role with write access.

Once a role that maps to the confidential client’s token has write access, uploads work without any further manual steps. Projects are created automatically on first upload.

Common API Operations¶

Create a namespace¶

curl -s -X POST \
  "https://docroot.example.com/api/namespaces" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "myns", "public_read": false}'

Upload documentation¶

The project is created automatically on first upload. The namespace must already exist.

curl -s -X POST \
  "https://docroot.example.com/api/namespaces/myns/\
projects/myproject/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@docs.zip" \
  -F "version=1.0.0" \
  -F "locale=en" \
  -F "ref=latest"

The ZIP must contain index.html at the archive root.

The ref field is optional. Omit it to upload the version without attaching any ref.

Managing Refs¶

Refs are named pointers to versions (like git tags or Docker tags). latest is conventional but has no special meaning.

# Create or update a ref
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": "1.0.0"}' \
  https://docroot.example.com/api/namespaces/myns/\
projects/myproject/refs/latest

# List all refs for a project
curl -H "Authorization: Bearer $TOKEN" \
  https://docroot.example.com/api/namespaces/myns/\
projects/myproject/refs

# Delete a ref (the version is not affected)
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://docroot.example.com/api/namespaces/myns/\
projects/myproject/refs/latest

Deleting a version does not remove refs that point to it. The ref is kept; resolving it returns a 404 until the ref is updated or deleted.

Access Control¶

ACL roles can be managed via the API or through the Manage Access button (shield icon) on each namespace in the UI. Write access to the namespace is required.

# Read current ACL
curl -H "Authorization: Bearer $TOKEN" \
  https://docroot.example.com/api/namespaces/myns/acl

# Grant a role write access
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": true, "write": true}' \
  https://docroot.example.com/api/namespaces/myns/acl/roles/my-role

# Revoke a role
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  https://docroot.example.com/api/namespaces/myns/acl/roles/my-role

REST API Reference¶

The full API reference is available at /api/docs (Swagger UI) when the backend is running.

Key endpoints¶

Method	Path	Description
`GET`	`/api/namespaces`	List visible namespaces
`POST`	`/api/namespaces`	Create a namespace
`DELETE`	`/api/namespaces/{ns}`	Delete (creator only)
`GET`	`/api/namespaces/{ns}/acl`	Read ACL
`PUT`	`/api/namespaces/{ns}/acl/roles/{role}`	Add/update role
`DELETE`	`/api/namespaces/{ns}/acl/roles/{role}`	Remove role
`PATCH`	`/api/namespaces/{ns}/owner`	Transfer ownership
`GET`	`/api/namespaces/{ns}/projects`	List projects
`POST`	`/api/namespaces/{ns}/projects`	Create a project
`GET`	`/api/namespaces/{ns}/projects/{p}/versions`	List versions
`POST`	`/api/namespaces/{ns}/projects/{p}/upload`	Upload version
`GET`	`/api/namespaces/{ns}/projects/{p}/resolve/{v}/{l}`	Resolve
`GET`	`/api/namespaces/{ns}/projects/{p}/refs`	List refs
`PUT`	`/api/namespaces/{ns}/projects/{p}/refs/{ref}`	Create/update ref
`DELETE`	`/api/namespaces/{ns}/projects/{p}/refs/{ref}`	Delete ref
`GET`	`/api/oidc-config`	OIDC public client config