Docsheaf
Sign inStart for free
Developers

Everything in Docsheaf, over a REST API

Manage organizations, content, change requests and docs sites with JSON over HTTPS — described in OpenAPI and authenticated with personal tokens.

API reference Create a token

Quickstart

From zero to your first request in a minute.

  1. 1

    Create a personal token

    In Account settings → API tokens. A token acts as you, with your permissions, and is shown only once.

  2. 2

    Call the API

    Send requests to /api/v1 on your Docsheaf app with an Authorization: Bearer dsk_… header.

  3. 3

    Explore the reference

    Browse every endpoint in the interactive reference, or download the OpenAPI document.

Terminal
export DOCSHEAF=https://app.example.com   # your Docsheaf app URL
export DOCSHEAF_TOKEN=dsk_…

# Who am I, and which organizations can I see?
curl -H "Authorization: Bearer $DOCSHEAF_TOKEN" "$DOCSHEAF/api/v1/user"

# List the spaces in an organization
curl -H "Authorization: Bearer $DOCSHEAF_TOKEN" "$DOCSHEAF/api/v1/orgs/$ORG_ID/spaces"

# Read a page as Markdown
curl -H "Authorization: Bearer $DOCSHEAF_TOKEN" \
  "$DOCSHEAF/api/v1/spaces/$SPACE_ID/content/pages/$PAGE_ID/markdown"

# Import Markdown as a new page on the main branch
curl -X POST "$DOCSHEAF/api/v1/spaces/$SPACE_ID/content/import" \
  -H "Authorization: Bearer $DOCSHEAF_TOKEN" -H "Content-Type: application/json" \
  -d '{"title": "Release notes", "markdown": "# Release notes\n..."}'

What you can automate

The web app is built on the same API, so anything you can do in Docsheaf you can script.

Organizations

Members, roles, invites, organization search and the audit log (CSV export for admins).

Spaces and content

Page trees, pages and documents, moves, Markdown import and Markdown export — on main or any change request.

Change requests

Open, diff, review, comment, update from main and merge, with conflict resolutions.

Docs sites

Create sites, order their spaces, customize the theme, publish, unpublish and rotate share links.

Insights

Views, visitors, feedback, top searches and content gaps for any site.

Files

Upload images and attachments (up to 20 MB) and reference them from documents.

Content routes work the same on a space’s main branch (/spaces/:spaceId) and on a change request (/spaces/:spaceId/change-requests/:number), so scripts can stage edits for review.

Predictable conventions

One error shape, explicit conflicts and no surprises.

  • Errors always look like { error: { code, message, details } }, with a stable machine-readable code.
  • Concurrent edits: document saves send the baseVersion they started from and get 409 version_conflict instead of overwriting someone else’s work.
  • Merge conflicts return 409 merge_conflict with the conflicting pages; resend the merge with a resolution per page.
  • Privacy: resources you can’t access return 404, so IDs don’t reveal what exists.
  • Published content has its own anonymous endpoints — site, page, Markdown, search and llms.txt — for custom readers.
Error response
HTTP/1.1 400 Bad Request
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": [{ "path": "/markdown", "message": "Invalid input: expected string, received undefined" }]
  }
}

Frequently asked questions

Where is the API reference?

At /api/reference on your Docsheaf app — an interactive reference generated from the OpenAPI document, which you can also download from /api/openapi.json.

Is there an official SDK?

Not yet. The API is described in OpenAPI 3, so you can generate a typed client with your usual tooling.

Can I limit what a token can do?

Tokens act as you, with your role in each organization. Organizations that require two-factor authentication reject tokens from members who haven’t enabled it.

Are there webhooks?

Yes. Organization admins add them under Settings → Webhooks: Docsheaf POSTs signed JSON (HMAC-SHA256 in the Docsheaf-Signature header) when change requests are opened, merged or archived, reviews and comments are posted, published content changes, and sites are published or unpublished. Failed deliveries are retried and can be sent again.

Are there rate limits?

Sign-in, sign-up and sensitive account endpoints are rate-limited and return 429 when you go over.

Build on your docs

Create a free account, generate a token and make your first request.

Start for freeTalk to us