---
title: API reference
description: The complete Docsary control surface — every endpoint you can call, its method, and its purpose.
order: 7
---

# 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](/api/conventions) 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 |

### Sites — [details](/api/sites)

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

### Versions — [details](/api/versions)

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

### Pages — [details](/api/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 |

### Assets — [details](/api/assets)

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

### Redirects — [details](/api/redirects)

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/sites/:site/redirects` | Read the redirect table |
| `PUT` | `/v1/sites/:site/redirects` | Replace the redirect table |

### Domains — [details](/api/domains)

| 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](/api/sites#create-a-site).

### Publishing — [details](/api/publish)

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

### Reports — [details](/api/reports)

| 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](/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](/api/conventions#authentication). Getting one is covered in [Access](/access).