Pages & Content API
Read and write documentation content programmatically — the API behind the web editor.
These endpoints power the web editor and let you read and write documentation content programmatically. All paths are relative to /v1/projects/{projectId}.
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.
| Endpoint | Description |
|---|---|
GET /pages | List the editable files |
GET /pages/{path}/content | Read a file, its sha, last commit and who else has it open |
PUT /pages/{path}/content | Commit one file |
POST /pages/save | Commit several files in one commit, with conflict detection |
POST /pages/{path}/presence · DELETE …/presence | Heartbeat while a file is open; leave when it closes |
POST /pages/{path}/lint | Check a page or syntext.json without saving, including deprecated syntax |
POST /pages/{path}/preview | Render MDX to HTML |
POST /reviews | Open a pull request for review |
POST /editor/files | Create a page |
DELETE /editor/files/{path} | Delete a page |
POST /editor/chat | Chat with the editor's Assistant; it proposes changes and never commits |
GET /editor/session | The editor assistant's session and context |
DELETE /editor/session | Clear one of your assistant sessions — body { sessionId }, returns { cleared: true } |
POST /editor/preview | Compile MDX — body { content }, returns { html, frontmatter, headings } |
POST /editor/validate | Check MDX compiles — body { content }, returns { valid, errors: [{ line, column, message }] } |
GET /editor/catalogue | Components, props, frontmatter keys, icon names and @stx tags the renderer supports |
GET /editor/symbols | The 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
/v1/projects/{projectId}/pagesReturns 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.
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
/v1/projects/{projectId}/pages/{path}/contentReturns a file's raw content and its blob sha. Reading a file also records you as having it open — see Page Presence.
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
/v1/projects/{projectId}/pages/{path}/contentCommits one file to the project's branch — or, on a project written in Syntext, saves it as a draft revision.
contentshasha 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.messagedocs: update <path>.publishbuild — { 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.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
/v1/projects/{projectId}/pages/saveCommits 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
/v1/projects/{projectId}/pages/{path}/presenceHeartbeat while a file is open, and DELETE on the same path when it closes. See Page Presence.
Lint a Page
/v1/projects/{projectId}/pages/{path}/lintChecks 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:
| code | Severity | When |
|---|---|---|
component/unknown | error | A tag that isn't a Syntext component. Opening and closing tags are reported separately |
prop/unknown | error | A prop the component doesn't have |
prop/value | error | A quoted value an enum prop doesn't allow. The message lists the allowed values |
fence/unclosed | error | A 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.
Preview a Page
/v1/projects/{projectId}/pages/{path}/previewCompiles supplied MDX and returns rendered HTML — used for live preview in the editor.
Request a Review
/v1/projects/{projectId}/reviewsCommits 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
/v1/projects/{projectId}/editor/filesCreates 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
/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
/v1/projects/{projectId}/editor/sessionReturns 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.
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
/v1/projects/{projectId}/editor/catalogueReturns 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
/v1/projects/{projectId}/editor/chatSends 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
/v1/projects/{projectId}/editor/symbolsReturns 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:
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:
| Status | Code | When |
|---|---|---|
| 400 | bad_request | No repository, an invalid repository URL, or no GitHub App installation |
| 400 | invalid_path | The path breaks the path rules |
| 403 | installation_not_owned | The installation is not connected to the project's workspace |
| 404 | not_found | The repository, branch or file does not exist |
| 409 | content_source_upload | The project is published with stx deploy; its files aren't stored in Syntext |
| 429 | rate_limited | Too many editor chat or symbols requests. Wait details.retryAfterSeconds |
| 500 | internal_error | The GitHub integration is temporarily unavailable |
| 502 | github_error | GitHub refused the request. details.githubStatus is GitHub's status; GitHub's response body is not passed through |
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.