Document Generation

What the API does

This is useful when the final documentation must be built in CI, triggered by a webhook, served from an internal system, or generated on demand from templates and variables.

This mechanism is configured at the document level and is separate from section content sync. Section content sync replaces one section, while this API returns the full generated HTML document.

How to enable it

1. Open the target document in the workspace.
2. Go to the document settings.
3. Open the Document generation API block.
4. Enable the API and save the document.
5. Copy the generated secret key and endpoint.

This feature is available on the Pro plan only. If the API is disabled, the key is cleared immediately. If the key is exposed, rotate it and update the integration.

Endpoint and authorization

Send requests to this server endpoint:

POST /api/document-generate/:syncKey

Replace :syncKey with the secret key of the target document. This method does not use a separate authorization header: possession of the key is the authorization mechanism.

Because of that, treat the key as a secret, keep it out of public frontend code, and avoid writing it into open logs.

What the endpoint returns

On success, the server returns 200 OK and immediately streams the generated HTML document as a downloadable file.

The successful response uses text/html; charset=utf-8. It does not return JSON on success.

Request format

The API accepts JSON. Every request field is optional. If the body is empty, the server builds the document from its current saved state.

{
  "saveContent": true,
  "variables": [
    { "key": "productName", "value": "Atlas SDK" }
  ],
  "pages": [
    {
      "sectionId": "release-notes",
      "title": "Release notes",
      "content": "<h1>Release notes</h1><p>Generated in CI.</p>",
      "saveContent": false
    },
    {
      "sectionId": "build-report",
      "type": "page",
      "title": "Build report",
      "content": "<h1>Build report</h1><p>This page exists only in the generated file.</p>",
      "parentSectionId": "release-notes",
      "position": 10
    }
  ],
  "styles": {
    "customCss": ".hero { color: #0f172a; }",
    "externalCssUrls": ["https://cdn.example.com/docs.css"],
    "minifyCss": true
  },
  "scripts": {
    "customScripts": "console.log('generated');",
    "externalScriptUrls": ["https://cdn.example.com/docs.js"],
    "minifyScripts": true
  }
}

variables replaces the document variables for this generation run. That lets you build the same document with a different set of values.

pages lets you override the content and titles of specific pages for this generation run. It supports page, API Reference, dynamic, and link sections. For dynamic, the navigation placement and root-page TOC visibility configured in the editor are preserved.

If pages[].sectionId does not match a saved section, the API adds a temporary section to the generated document. Temporary sections are never saved, even when the root or page-level saveContent value is true. The type field defaults to page. Use parentSectionId to place it under a saved section or an earlier temporary section from the same request, and use position to control its order. Without a parent, it is appended at the document root.

Temporary sections also accept the regular rendering fields: title, content, link, target, hiddenInMenu, generatesToc, sectionLanguage, custom CSS and scripts, external asset URLs, minification flags, and dynamic navigation settings. Temporary API Reference and dynamic sections must provide valid content.

saveContent is false by default. Set it to true at the request root to save every provided pages[].content value on the server after the document has been built. A page-level pages[].saveContent value overrides the root setting for that section. Only content for page, API Reference, and dynamic sections is saved; titles, links, variables, styles, and scripts remain temporary generation overrides.

For API Reference, pages[].content must contain a valid extractor JSON string, not HTML.

styles and scripts let you temporarily override document-level CSS, JavaScript, and external asset URLs for the current generation run. These fields are also Pro-only, like the whole API.

const endpoint = "https://onefiledocs.com/api/document-generate/DOCUMENT_SECRET";

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    saveContent: true,
    variables: [
      { key: "productName", value: "Atlas SDK" },
    ],
    pages: [
      {
        sectionId: "release-notes",
        content: "<h1>Release notes</h1><p>Generated in CI.</p>",
        saveContent: true,
      },
    ],
  }),
});

const html = await response.text();

If the integration needs the raw HTML string, read it with response.text(). If it needs a file, use the response body as a blob and save it directly without JSON parsing.

Errors and limits

If the request body is invalid, saveContent is not a boolean, a temporary section points to a missing parent, or invalid extractor JSON is sent for API Reference, the server returns 400 Bad Request.

If the document generation API is disabled for the document or the owner no longer has an active Pro plan, the server returns 403 Forbidden.

If the key is not found, the server returns 404 Not Found.

The server always builds one final HTML document. This endpoint does not support switching response formats.