On this page
API reference
The API is the entire control surface. Everything a docs site can be or do is reachable from here, and nothing is reachable any other way — which is what makes a docs site something your CI can own end to end.
Base URL:
https://api.docsary.com/v1
Start with Conventions and errors for authentication, identifiers, and error shapes.
Every endpoint below takes your organization API key. Mutations need a write-capable key; GET requests work with a read-only one.
Every endpoint
Service
| Method |
Path |
Purpose |
GET |
/__health |
Liveness check (no token) |
GET |
/v1 |
Endpoint index (no token) |
GET |
/v1/whoami |
Identify the calling key — organization, plan, scopes |
| Method |
Path |
Purpose |
GET |
/v1/sites |
List your sites |
POST |
/v1/sites |
Create a site |
GET |
/v1/sites/:site |
Site with versions and domains |
PATCH |
/v1/sites/:site |
Rename, set settings, set default version |
DELETE |
/v1/sites/:site |
Delete a site and everything in it |
| Method |
Path |
Purpose |
GET |
/v1/sites/:site/versions |
List versions |
POST |
/v1/sites/:site/versions |
Create a version |
PATCH |
/v1/sites/:site/versions/:ver |
Rename, reslug, reposition |
DELETE |
/v1/sites/:site/versions/:ver |
Delete a version and its pages |
| Method |
Path |
Purpose |
GET |
/v1/sites/:site/versions/:ver/pages |
Page list plus navigation tree |
POST |
/v1/sites/:site/versions/:ver/import |
Bulk import and prune |
GET |
/v1/sites/:site/versions/:ver/export |
Whole version back as markdown |
GET |
/v1/sites/:site/versions/:ver/pages/* |
One page, markdown or HTML |
PUT |
/v1/sites/:site/versions/:ver/pages/* |
Create or replace one page |
DELETE |
/v1/sites/:site/versions/:ver/pages/* |
Delete one page |
| Method |
Path |
Purpose |
GET |
/v1/sites/:site/assets |
List assets |
POST |
/v1/sites/:site/assets/* |
Upload or replace an asset |
DELETE |
/v1/sites/:site/assets/* |
Delete an asset |
| Method |
Path |
Purpose |
GET |
/v1/sites/:site/redirects |
Read the redirect table |
PUT |
/v1/sites/:site/redirects |
Replace the redirect table |
| Method |
Path |
Purpose |
GET |
/v1/sites/:site/domains |
List the site's hostnames |
POST |
/v1/sites/:site/domains |
Attach a hostname you own |
POST |
/v1/sites/:site/domains/:hostname/verify |
Prove ownership and start serving |
DELETE |
/v1/sites/:site/domains/:hostname |
Detach a hostname |
Every site is given a docsary.com address when it is created, with no call needed — see Create a site.
| Method |
Path |
Purpose |
POST |
/v1/sites/:site/publish |
Refresh every cached page for the site |
POST |
/v1/sites/:site/rerender |
Re-render stored markdown in chunks |
| Method |
Path |
Purpose |
POST |
/v1/reports |
File a bug report or a feature request |
GET |
/v1/reports |
List your organization's reports and their status |
Unlike everything above, these two accept a read-only key as well as a write-capable one — reporting a problem is not a change to your content. See Support.
Keys
One kind of token owns content: your organization API key (dsy_...). Everything under /v1/sites requires one, and each key sees only its own organization's sites. Keys are write-capable or read-only — see Conventions. Getting one is covered in Access.