Content Updates

This API lets an external service or script replace the content of a specific section without opening the One File Docs editor.

What the API does

This is useful when content is built in CI, comes from a CMS, is generated by a separate process, or must be refreshed after an event in another system.

The API works only for page and API Reference section types. Access is controlled by a secret section key stored in the external update settings.

How to enable it

  1. Open the target document in the workspace.
  2. Go to a page or API Reference section.
  3. Open the External content updates block.
  4. Enable the API and save the section.
  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 revoked immediately. If the key is exposed, rotate it and update the integration.

Endpoint and authorization

Send requests to this server endpoint:

POST /api/content-sync/:syncKey

Replace :syncKey with the secret key of the target section. This endpoint 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.

Request format

The API accepts JSON with a string field named content.

{
  "content": "<h1>Updated content</h1><p>Generated externally.</p>"
}

For a page section, content must contain an HTML string that fully replaces the current section content.

For an API Reference section, content must still be a string, but that string must contain valid extractor JSON. The server validates and normalizes it before saving.

const endpoint = "https://onefiledocs.com/api/content-sync/SECTION_SECRET";
const html = "<h1>Release notes</h1><p>Synced from CI.</p>";

await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: html,
  }),
});

For API Reference, the only difference is the value of content: send a JSON string there instead of HTML.

Successful response

On success, the server returns 200 OK with a JSON payload:

{
  "status": "ok",
  "documentId": 12,
  "sectionId": 34,
  "sectionIdentifier": "release-notes",
  "sectionType": "page",
  "updatedAt": "2026-07-01T07:00:00.000Z"
}

sectionIdentifier is the section slug inside the document. updatedAt is returned in UTC ISO format.

Errors and limits

If the key is empty, the request body is invalid, or content is not a string, the server returns 400 Bad Request.

If the section type is unsupported, external updates are disabled, or the document 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.

For API Reference, invalid extractor JSON also results in 400 Bad Request.

Each call fully replaces the current section content. There is no partial merge on the server, so the integration must send the full current content each time.