REST API

Overview

The Documentation.AI REST API provides programmatic access to your documentation project through a standard REST interface. You can read pages, search content, manage branches, push file changes, publish deployments, export your site as a PDF, and read analytics, the same operations available in the dashboard, accessible from your own scripts, CI/CD pipelines, or backend services.

Every key is scoped to one documentation project, so no endpoint takes a project identifier.

The Documentation.AI REST API and the Authoring MCP Server cover largely the same documentation-management actions through different interfaces. Use the REST API when you need direct HTTP access from scripts, backends, or CI/CD, and use the Authoring MCP Server when you are working from an MCP-compatible AI client or agent.

Prerequisites

Before using the Documentation.AI REST API, make sure you have the following:

1. A Documentation.AI account on the Standard plan or above
2. A published documentation project with a connected repository
3. Admin access to the organization that owns the documentation project (required to create API keys)

Getting Your API Key

1. Open the Documentation.AI Dashboard
2. Select the documentation project you want to access
3. Go to Settings → API Keys
4. Click Create Key
5. Choose a name, role (Viewer, Editor, or Admin), and expiration
6. Copy the generated key immediately; it will only be shown once

Base URL

https://api.documentationai.app/api/v1

Authentication

All requests require an API key passed as a Bearer token in the Authorization header.

curl https://api.documentationai.app/api/v1/pages \
  -H "Authorization: Bearer dai_your_api_key"

API keys are generated from the dashboard under Settings → API Keys. Each key is scoped to a single documentation project.

Roles and Permissions

Every API key carries a role that determines which endpoints are accessible.

Write endpoints return 403 Forbidden if the API key role does not have sufficient permissions.

Deploying sits behind editor because it publishes to your live site. Analytics is read-only, so a viewer key is enough.

Starting a PDF export needs editor. Reading the current export, and the link it carries, needs only viewer.

Rate Limiting

Each API key has a per-minute request limit configured at creation time, counted across every endpoint. Starting a PDF export has an additional limit of 10 requests a minute per key.

Rate limit information is included in every response via headers:

When a request counts against more than one limit, the headers describe the limit closest to being reached.

When a limit is exceeded, the API returns 429 Too Many Requests.

Quick Example

List all pages in your documentation:

curl https://api.documentationai.app/api/v1/pages \
  -H "Authorization: Bearer dai_your_api_key"

const response = await fetch('https://api.documentationai.app/api/v1/pages', {
  headers: { 'Authorization': 'Bearer dai_your_api_key' }
});
const data = await response.json();
console.log(data.pages);

import requests

response = requests.get(
    'https://api.documentationai.app/api/v1/pages',
    headers={'Authorization': 'Bearer dai_your_api_key'}
)
print(response.json()['pages'])

Push Changes

Create, update, or delete files in a single commit:

curl -X POST https://api.documentationai.app/api/v1/push \
  -H "Authorization: Bearer dai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "commitMessage": "Update getting started guide",
    "operations": [
      {
        "type": "update",
        "path": "getting-started/quickstart.mdx",
        "content": "---
title: Quickstart
---

Updated content here."
      }
    ]
  }'

Deployments

Pushing already deploys, so you only need /deploy when nothing changed in Git. The common case is an OpenAPI specification you reference by URL: it changed on your own host, so no commit exists to trigger a rebuild.

curl -X POST https://api.documentationai.app/api/v1/deploy \
  -H "Authorization: Bearer dai_your_api_key"

The response is 202 Accepted with a deployment to poll, not a finished build:

{
  "deploymentId": "9f1c2e64-3b47-4a8d-91f5-7c2e0a6d5b31",
  "status": "pending",
  "url": "https://docs.acme.com"
}

Poll it until status reaches ready or error:

curl https://api.documentationai.app/api/v1/deployments/9f1c2e64-3b47-4a8d-91f5-7c2e0a6d5b31 \
  -H "Authorization: Bearer dai_your_api_key"

When the status is error, the logs field carries the reason.

PDF Exports

Export your live site as a single PDF, for offline reading, compliance archives, or sharing outside your docs. Pages are rendered in navigation order. PDF export is available on the Professional and Enterprise plans.

Start an export:

curl -X POST https://api.documentationai.app/api/v1/exports/pdf \
  -H "Authorization: Bearer dai_your_api_key"

The response is 202 Accepted with an export to poll:

{
  "exportId": "6fa5a52d-d8b7-4b24-ac92-a55378f5eec4",
  "status": "pending",
  "progress": { "completed": 0, "total": null },
  "fileSize": null,
  "downloadUrl": null,
  "downloadUrlExpiresAt": null,
  "deploymentId": "64e41663-5ac8-422e-a941-00aff79963ed",
  "source": "api",
  "errorMessage": null,
  "createdAt": "2026-09-17T13:04:12.000Z",
  "completedAt": null
}

Poll GET /exports/pdf until downloadUrl appears. It always returns the export in progress, or the most recent one, so there is no id to keep between calls. progress counts pages as they render:

curl https://api.documentationai.app/api/v1/exports/pdf \
  -H "Authorization: Bearer dai_your_api_key"

Then download the PDF from the link, with no API key:

curl -o documentation.pdf "$DOWNLOAD_URL"

The link points straight at our storage, so the file never passes through the API and a large export downloads at full speed. It stops working after an hour, or once a newer export replaces the file; read the export again for a fresh one.

Reusing an export

If your live site has not changed since the last completed export, POST /exports/pdf returns that export with 200 OK instead of rendering again. This makes it safe to call on every CI run. To render again anyway, pass force:

curl -X POST https://api.documentationai.app/api/v1/exports/pdf \
  -H "Authorization: Bearer dai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "force": true }'

Limits

• One export runs per documentation at a time. Starting another returns 409 Conflict; poll GET /exports/pdf to follow the one already running.
• Exports started through the API are limited to one every 5 minutes and 10 per 24 hours for each documentation. Past either limit, the API returns 429 with a retry-after header. A request answered with an existing export does not count, and neither do exports started from the dashboard. force does not bypass these limits.
• A site can be exported with up to 8,000 pages in its navigation.

The exported file

• A PDF stays available until a newer export of the same documentation completes and replaces it. Only the most recent export is kept.
• A page that cannot be rendered, for example because its MDX does not compile, is left out of the PDF rather than failing the export.
• Exports started from the dashboard appear here too, so exportId can change between polls if a teammate starts one while yours is running.

Analytics

Analytics endpoints are read-only, so a viewer key is enough.

Dates are whole UTC days in YYYY-MM-DD form, and endDate is inclusive. Omit them to get the last seven days. A single request covers at most 90 days; ask for more and you get 400.

Find the questions your AI assistant answered least confidently, which is the fastest way to spot gaps in your documentation:

curl -G https://api.documentationai.app/api/v1/analytics/ai/questions \
  -H "Authorization: Bearer dai_your_api_key" \
  -d startDate=2026-05-01 \
  -d endDate=2026-05-31 \
  -d maxConfidence=0.5

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "questions": [
    {
      "question": "how do I rotate an API key?",
      "answer": "I could not find anything about rotating keys in the documentation.",
      "pagePath": "/docs",
      "sessionId": "ms4f2jlbbsym28yd",
      "confidenceScore": 0.21,
      "askedAt": "2026-05-14T09:22:11.108Z"
    }
  ],
  "total": 40
}

Page through results with limit and offset, using total to know when to stop. /analytics/pages and /analytics/referrers are the exception: they are top-N rankings, so they take a limit but cannot be paged.

The two daily series, /analytics/traffic and /analytics/ai/volume, return one entry per day including days with no activity, so you can chart them without filling gaps yourself.

Search Analytics

Search analytics endpoints show how readers use search and where they run into dead ends. All four endpoints accept the same date range rules as other analytics endpoints.

Get a summary of search activity:

curl -G https://api.documentationai.app/api/v1/analytics/search \
  -H "Authorization: Bearer dai_your_api_key" \
  -d startDate=2026-08-01 \
  -d endDate=2026-08-31

{
  "startDate": "2026-08-01",
  "endDate": "2026-08-31",
  "totalSearches": 1240,
  "sessions": 820,
  "noResultRate": 0.15,
  "clickThroughRate": 0.42
}

Get daily search volume for charting:

curl -G https://api.documentationai.app/api/v1/analytics/search/volume \
  -H "Authorization: Bearer dai_your_api_key" \
  -d startDate=2026-08-01 \
  -d endDate=2026-08-31

Get the most popular search queries, or filter to only no-result queries:

curl -G https://api.documentationai.app/api/v1/analytics/search/queries \
  -H "Authorization: Bearer dai_your_api_key" \
  -d startDate=2026-08-01 \
  -d endDate=2026-08-31 \
  -d noResultsOnly=true \
  -d limit=20

Get per-page search performance to find where searches most often fail:

curl -G https://api.documentationai.app/api/v1/analytics/search/results \
  -H "Authorization: Bearer dai_your_api_key" \
  -d startDate=2026-08-01 \
  -d endDate=2026-08-31

Page through query results with limit and offset, using total to know when to stop.

Endpoints

See the endpoint reference below for complete details on every available operation, including request parameters, response schemas, and examples.