/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API API Reference Pages & Content API

Pages & Content API

Read and write documentation content programmatically — the API behind the web editor.

11 min read

These endpoints power the web editor and let you read and write documentation content programmatically. All paths are relative to /v1/projects/{projectId}.

Note

Every endpoint needs a signed-in member of the workspace, with a session JWT — API keys are refused with 401. You must be a member of the organization that owns {projectId}: a non-member gets 403, and a missing or deleted project returns 404. There is no further role check — any member can read, save and delete pages — and no plan gate.

The endpoints that read or commit to the repository use the project's GitHub App installation, which must be connected to the project's workspace. Otherwise they return 403 installation_not_owned — see Connecting a GitHub App installation.

Projects published with stx deploy have no stored files, so these endpoints return 409 content_source_upload for them — import the files first with Import Content.

Projects written in Syntext use the same endpoints, with no repository or GitHub App. A save writes a new draft revision instead of a commit: it doesn't change the live site until you publish — pass publish: true on a save, or call Publish Content. commitSha is the revision's id, and the response adds revision — { id, number }. History, restore, upload and publish have their own endpoints — see Content.

EndpointDescription
GET /pagesList the editable files
GET /pages/{path}/contentRead a file, its sha, last commit and who else has it open
PUT /pages/{path}/contentCommit one file
POST /pages/saveCommit several files in one commit, with conflict detection
POST /pages/{path}/presence · DELETE …/presenceHeartbeat while a file is open; leave when it closes
POST /pages/{path}/lintCheck a page or syntext.json without saving, including deprecated syntax
POST /pages/{path}/previewRender MDX to HTML
POST /reviewsOpen a pull request for review
POST /editor/filesCreate a page
DELETE /editor/files/{path}Delete a page
POST /editor/chatChat with the editor's Assistant; it proposes changes and never commits
GET /editor/sessionThe editor assistant's session and context
DELETE /editor/sessionClear one of your assistant sessions — body { sessionId }, returns { cleared: true }
POST /editor/previewCompile MDX — body { content }, returns { html, frontmatter, headings }
POST /editor/validateCheck MDX compiles — body { content }, returns { valid, errors: [{ line, column, message }] }
GET /editor/catalogueComponents, props, frontmatter keys, icon names and @stx tags the renderer supports
GET /editor/symbolsThe repository's @stx-annotated symbols, for {@embed}

Paths

Editor paths are relative to the project's docs folder (its repoPath), with forward slashes — guides/quickstart.mdx, not /docs/guides/quickstart.mdx. In a URL, encode the whole path as one segment: guides%2Fquickstart.mdx.

The repository-root config files syntext.json, syntext.yaml, syntext.yml and syntext.config.json are addressed by their bare name and resolve to the repository root, which is where the build reads them — even when your docs live in a subfolder.

A path that would leave the docs folder is refused with 400 invalid_path and details.path: an absolute path, a backslash, a control character, or an empty, . or .. segment.

List Pages

GET/v1/projects/{projectId}/pages

Returns every .md and .mdx file under the docs folder at the head of the project's branch — index files first, then by path — followed by the root config files that exist.

json
{
"data": [
{ "path": "index.mdx", "title": "Index", "lastModified": "", "order": 0 },
{ "path": "guides/quickstart.mdx", "title": "Quickstart", "lastModified": "", "order": 1 },
{ "path": "guides/drafts.mdx", "title": "Drafts", "lastModified": "" },
{ "path": "syntext.json", "title": "syntext.json", "lastModified": "", "outsideRoot": true }
]
}
•
title is derived from the file name. lastModified is always an empty string.
•
order is the page's 0-based position in the navigation of syntext.json (or syntext.config.json), counted across groups and nested groups in order. A navigation entry matches the path without its extension, and x/index also matches x. Pages that are not in the navigation have no order. YAML configs are not read for order.
•
outsideRoot: true marks a repository-root config file.

Get Page Content

GET/v1/projects/{projectId}/pages/{path}/content

Returns a file's raw content and its blob sha. Reading a file also records you as having it open — see Page Presence.

json
{
"data": {
"content": "---\ntitle: Quickstart\n---\n\n# Quickstart\n...",
"sha": "3f1c9a7e2b4d6f8a0c1e3b5d7f9a1c3e5b7d9f1a",
"lastCommit": { "author": "Ada Lovelace", "at": "2026-11-08T15:52:10Z" },
"editors": [{ "name": "Grace Hopper" }]
}
}
•
sha — keep it and send it back when you save, so the save is conflict-checked.
•
lastCommit — the latest commit that touched the file. Left out when it cannot be looked up.
•
editors — the other people who have opened the file, or sent a presence heartbeat for it, in the last 120 seconds. You are not listed. Names are display names, or the part of the email address before the @.

A file that does not exist returns 404 not_found.

Update Page Content

PUT/v1/projects/{projectId}/pages/{path}/content

Commits one file to the project's branch — or, on a project written in Syntext, saves it as a draft revision.

NameDescription
content:stringbodyRequired
The file's full new content.
sha:stringbody
The sha you read the file at. If the file changed since, the API returns 409 save_conflict and writes nothing. Omit it to overwrite without a check.
message:stringbody
Commit message, up to 500 characters. Defaults to docs: update <path>.
publish:booleanbody
Projects written in Syntext only: also publish the project after saving. The response then has build — { id, status }, { skipped: "usage_limit", current, limit } when the plan's builds are used up, or null if the publish couldn't start. The draft is saved either way.
json
{
"data": {
"sha": "c2a8e4f6b0d1c3e5a7b9d1f3e5c7a9b1d3f5e7c9",
"commitSha": "9d4e1b7c3a5f8e2d6b0c4a9f1e7d3b5c8a2f6e0d"
}
}

Unlike POST /pages/save, this does not start a build on a GitHub project. On a project written in Syntext the response also has revision.

Batch Save

POST/v1/projects/{projectId}/pages/save

Commits up to 100 files in one commit and starts a build — or, on a project written in Syntext, saves them as one draft revision. Each file may carry the sha it was opened at. Returns the commitSha and each file's new sha. See Save Pages.

Page Presence

POST/v1/projects/{projectId}/pages/{path}/presence

Heartbeat while a file is open, and DELETE on the same path when it closes. See Page Presence.

Lint a Page

POST/v1/projects/{projectId}/pages/{path}/lint

Checks supplied content and returns diagnostics without saving. Each diagnostic is { line, severity, message, code?, fix? }. The editor Assistant's check_file tool runs the same checks, so the two never disagree.

For a page, it reports frontmatter and compile errors, then the same syntax checks the build runs: deprecated frontmatter keys, MDX tags and props (with the replacement), unknown frontmatter keys and invalid values (with "did you mean"). Then it checks components against the catalogue:

codeSeverityWhen
component/unknownerrorA tag that isn't a Syntext component. Opening and closing tags are reported separately
prop/unknownerrorA prop the component doesn't have
prop/valueerrorA quoted value an enum prop doesn't allow. The message lists the allowed values
fence/unclosederrorA code fence that is never closed, reported on its opening line

Frontmatter, code blocks, inline code and HTML comments are skipped; deprecated tag and prop names are reported by the deprecation check instead. key, className, id, style, data-* and aria-* are accepted on any component.

code is the deprecation code or one of the codes above. Frontmatter and compile errors have none.

fix, when present, is a one-click fix: { line, find, replace, label } — on line (1-based), replace the first occurrence of find with replace. label says what it does, such as Use Note. Fixes are offered for unknown components, props and values that have a close match: the same name in a different case, or one within two letters.

For syntext.json, syntext.yml or syntext.yaml as {path}, it checks the config instead of compiling it: whether it parses, values outside their allowed set, and deprecated or unknown keys.

A deprecated form is a warning, or an error once its removal date has passed — exactly when the build would fail on it.

json
{
"data": [
{ "line": 3, "severity": "warning", "code": "frontmatter.unknown-key", "message": "Unknown key \"descripton\" is ignored. Did you mean \"description\"?" },
{ "line": 12, "severity": "warning", "code": "mdx.update-label", "message": "<Update label=\"…\"> is deprecated. Use <Update title=\"…\"> instead." },
{
"line": 18,
"severity": "error",
"code": "component/unknown",
"message": "No component <Notee>. Did you mean <Note>?",
"fix": { "line": 18, "find": "<Notee", "replace": "<Note", "label": "Use Note" }
},
{
"line": 24,
"severity": "error",
"code": "prop/value",
"message": "\"Post\" is not a value of Endpoint method. Use one of: GET, POST, PUT, PATCH, DELETE.",
"fix": { "line": 24, "find": "\"Post\"", "replace": "\"POST\"", "label": "Use POST" }
}
]
}

Preview a Page

POST/v1/projects/{projectId}/pages/{path}/preview

Compiles supplied MDX and returns rendered HTML — used for live preview in the editor.

Request a Review

POST/v1/projects/{projectId}/reviews

Commits your changes to a new docs/review-… branch and opens a pull request against the project's branch. File paths follow the path rules. See also Collaboration.

Create a Page

POST/v1/projects/{projectId}/editor/files

Creates a page with generated frontmatter. path must be relative to the docs folder, with forward slashes and no . or .. segments. title, description and icon must be single lines. Anything else returns 400. Creating a page does not start a build.

Delete a Page

DELETE/v1/projects/{projectId}/editor/files/{path}

Deletes one .md or .mdx page in its own commit, optionally checked against ?sha=. See Delete Page File.

Editor Session

GET/v1/projects/{projectId}/editor/session

Returns your editor assistant session — sessionId, messages, createdAt, updatedAt — or { "sessionId": null, "messages": [] } when you have none. Either way the response includes context: what the assistant can draw on beyond the open file.

json
{
"data": {
"sessionId": null,
"messages": [],
"context": ["docs · acme-api", "@stx · acme-api"]
}
}

docs · <project slug> is always present. @stx · <project slug> is added when the project has API endpoints documented from @stx annotations. A GitHub project with no repository configured gets 400; a project published with stx deploy gets 409 content_source_upload.

Editor Catalogue

GET/v1/projects/{projectId}/editor/catalogue

Returns every MDX component with its props, every frontmatter key the build reads, every icon name and every @stx annotation tag — the list behind the editor's completions, block picker and component settings. It doesn't touch the repository. See Get Editor Catalogue.

Editor Chat

POST/v1/projects/{projectId}/editor/chat

Sends a message to the editor's Assistant and streams its reply. Send your unsaved files as openFile and files and it reads those instead of the repository. Its edits come back as proposals — it never commits. Limited to 20 requests per user, per project, per minute. See Editor Chat.

Editor Symbols

GET/v1/projects/{projectId}/editor/symbols

Returns the @stx-annotated symbols in the project's repository, each with its {@embed} value — from up to 200 code files, cached for 10 minutes per commit. Limited to 30 requests per user, per project, per minute. See Get Editor Symbols.

Conflict Handling

Pass the sha you read a file at when you save it. If someone else changed the file in the meantime — or, for a batch save, the branch moved while it was being written — the write is refused with 409 save_conflict and nothing is committed:

json
{
"error": {
"code": "save_conflict",
"message": "guides/quickstart.mdx was changed by someone else since you opened it. Reload it or keep your version.",
"details": {
"paths": ["guides/quickstart.mdx"],
"files": [
{
"path": "guides/quickstart.mdx",
"currentSha": "5e7a9c1b3d5f7e9a1c3b5d7f9e1a3c5b7d9f1e3a",
"lastCommit": { "author": "Ada Lovelace", "at": "2026-11-08T15:52:10Z" }
}
]
}
}
}

Re-fetch the file, merge your changes, and save again with the new sha — or omit sha to overwrite. Saves without sha are last-write-wins. See Save Pages for the full details shape.

Errors

Besides the errors above, the repository-backed endpoints share these:

StatusCodeWhen
400bad_requestNo repository, an invalid repository URL, or no GitHub App installation
400invalid_pathThe path breaks the path rules
403installation_not_ownedThe installation is not connected to the project's workspace
404not_foundThe repository, branch or file does not exist
409content_source_uploadThe project is published with stx deploy; its files aren't stored in Syntext
429rate_limitedToo many editor chat or symbols requests. Wait details.retryAfterSeconds
500internal_errorThe GitHub integration is temporarily unavailable
502github_errorGitHub refused the request. details.githubStatus is GitHub's status; GitHub's response body is not passed through
Warning

On a GitHub project, the save, update, create and delete endpoints commit directly to the project's branch in its connected repository, with the GitHub App's identity. Editor chat never does — the Assistant only proposes changes. Pull before you push from a local clone, or your push may be rejected as non-fast-forward.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext