Editor Chat
Send a message to the web editor's Assistant and stream its reply, with the changes it proposes to your unsaved files.
Sends a message to the web editor's Assistant and streams its reply. The Assistant reads your docs, checks pages and proposes changes. It never writes to the repository — edits, new pages and navigation changes come back as proposals for you to apply and save yourself.
Any member of the workspace can call this, signed in with a session JWT — API keys are refused with 401. You must belong to the organization that owns {projectId}. It reads the project's pages from its repository, through its GitHub App installation — see Pages & Content API — or, for a project written in Syntext, from Syntext. Projects published with stx deploy have no pages to read.
Limited to 20 requests per user, per project, per minute — see Rate limits.
Path Parameters
projectIdRequest Body
messagesessionIdX-Session-Id header has the session used; GET /v1/projects/{projectId}/editor/session returns your latest one with its history.openFile{ path, content }. The Assistant reads this copy instead of the repository's, treats it as "this page", and sends edits you ask for without naming a file to it.files{ path, content }. The Assistant reads these copies instead of the repository's.openFile and files are never saved. They seed a workspace for this one reply: the Assistant reads from it first and falls back to the repository, and each change it proposes is added to it, so later reads and checks in the same reply see earlier proposals.
Limits on openFile and files
| Rule | Limit |
|---|---|
path | 1–500 characters, relative to the docs folder, with forward slashes. No leading / or drive letter (C:), no empty, . or .. segments, and no control characters, backslashes or backticks |
content | At most 200,000 characters per file |
files | At most 10 entries |
| Total | openFile and every entry of files together at most 1,000,000 characters |
Anything outside these limits is refused with 400 validation_error, and details.issues names the field.
Response
200 with Content-Type: text/event-stream and the session in X-Session-Id. Each line is one part of the reply — a one-character type, a colon, and JSON:
| Prefix | Part | JSON |
|---|---|---|
0: | Reply text, streamed in pieces | A string |
9: | A tool call | { toolCallId, toolName, args } |
a: | A tool's result | { toolCallId, result } |
e: | An error during the reply | { error } |
The Assistant takes up to 10 steps per reply. The reply is saved to the session when the stream ends.
Proposals
edit_file, create_file and update_navigation return a proposal instead of writing anything:
successtrue when the change was proposed.pathsummaryaddedremovedproposal{ kind, path, before, after, summary }. kind is edit or create; before is the file as the Assistant read it (empty for create) and after is the full proposed content. Apply after to your own copy and save it with POST /pages/save to commit it.A refused proposal returns { success: false, path, code, message, diagnostics? }:
| code | When |
|---|---|
validation_error | The proposed page doesn't compile, the proposed config doesn't parse, or the change adds a component, prop or value the catalogue doesn't have (component/unknown, prop/unknown, prop/value). diagnostics lists the problems, and the Assistant corrects the content and proposes again |
no_change | The proposed content is the same as the file, or the page is already in that navigation group |
not_found | edit_file on a file that doesn't exist, or no site config for update_navigation |
exists | create_file on a file that already exists |
invalid_path | The path breaks the path rules |
Tools
| Tool | What it does |
|---|---|
list_files | Lists the documentation pages in the repository |
read_file | Reads a file: your copy from openFile or files when there is one (source: "editor"), else the repository's (source: "repo") |
edit_file | Proposes a change to an existing file, given its full new content and a one-line summary |
create_file | Proposes a new page with generated frontmatter. Refused when the file exists |
update_navigation | Proposes adding a page to a navigation group in syntext.json or the YAML config |
check_file | Checks a file with the same checks as Lint a Page and returns { errors, warnings, diagnostics }. Defaults to the open file; pass content to check a proposed version |
validate_mdx | Checks that some MDX compiles |
search_docs | Searches the existing documentation |
get_openapi_spec | Reads the project's OpenAPI spec, when one is configured |
get_syntext_config | Reads the site config and its navigation |
write_file has been removed, and no tool commits, creates a branch or writes to GitHub. Before this change the Assistant committed its edits to your branch directly; now nothing reaches the repository until you save.
Error Responses
400 Bad Request
validation_error — message is empty or longer than 4000 characters, sessionId isn't a UUID, or openFile or files break the limits. bad_request — the project has no repository configured.
401 Unauthorized
No session JWT, an expired one, or an API key.
403 Forbidden
forbidden — you are not a member of the organization that owns the project.
404 Not Found
not_found — the project does not exist or was deleted.
429 Too Many Requests
rate_limited — more than 20 chat requests from you on this project in the current minute. Wait details.retryAfterSeconds before sending again:
500 Internal Server Error
internal_error — the reply could not be started.