/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Editor Chat

Editor Chat

Send a message to the web editor's Assistant and stream its reply, with the changes it proposes to your unsaved files.

POST/v1/projects/{projectId}/editor/chatTry it
Session token

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.

Note

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

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

NameDescription
message:stringbodyRequired
Your message, 1–4000 characters.
sessionId:stringbody
UUID of one of your editor sessions on this project, to continue it. Omit it — or send one that isn't yours or doesn't exist — and a new session is started. The response's X-Session-Id header has the session used; GET /v1/projects/{projectId}/editor/session returns your latest one with its history.
openFile:objectbody
The file you have open, as it is in your editor — unsaved changes included: { 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:object[]body
Up to 10 other files with unsaved changes, each { 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

RuleLimit
path1–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
contentAt most 200,000 characters per file
filesAt most 10 entries
TotalopenFile 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:

PrefixPartJSON
0:Reply text, streamed in piecesA 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:

NameDescription
success:boolean
true when the change was proposed.
path:string
The file the proposal changes, relative to the docs folder.
summary:string
One line describing the change.
added:number
Lines added.
removed:number
Lines removed.
proposal:object
{ 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? }:

codeWhen
validation_errorThe 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_changeThe proposed content is the same as the file, or the page is already in that navigation group
not_foundedit_file on a file that doesn't exist, or no site config for update_navigation
existscreate_file on a file that already exists
invalid_pathThe path breaks the path rules

Tools

ToolWhat it does
list_filesLists the documentation pages in the repository
read_fileReads a file: your copy from openFile or files when there is one (source: "editor"), else the repository's (source: "repo")
edit_fileProposes a change to an existing file, given its full new content and a one-line summary
create_fileProposes a new page with generated frontmatter. Refused when the file exists
update_navigationProposes adding a page to a navigation group in syntext.json or the YAML config
check_fileChecks 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_mdxChecks that some MDX compiles
search_docsSearches the existing documentation
get_openapi_specReads the project's OpenAPI spec, when one is configured
get_syntext_configReads the site config and its navigation
Warning

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:

json
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Wait a moment and try again.",
"details": { "retryAfterSeconds": 42, "traceId": "4f7c2a9e1b3d" }
}
}

500 Internal Server Error

internal_error — the reply could not be started.

Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -N "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/editor/chat" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{
"message": "Add a warning about key expiry",
"openFile": {
"path": "guides/api-keys.mdx",
"content": "---\ntitle: API keys\n---\n\n# API keys\n\nCreate a key in Settings.\n"
}
}'
Responseapplication/json
text
9:{"toolCallId":"call_1","toolName":"read_file","args":{"path":"guides/api-keys.mdx"}}
a:{"toolCallId":"call_1","result":{"success":true,"path":"guides/api-keys.mdx","content":"---\ntitle: API keys\n...","size":61,"source":"editor"}}
9:{"toolCallId":"call_2","toolName":"edit_file","args":{"path":"guides/api-keys.mdx","content":"...","summary":"warn that keys expire after 90 days"}}
a:{"toolCallId":"call_2","result":{"success":true,"path":"guides/api-keys.mdx","summary":"warn that keys expire after 90 days","added":4,"removed":0,"proposal":{"kind":"edit","path":"guides/api-keys.mdx","before":"...","after":"...","summary":"warn that keys expire after 90 days"}}}
0:"I proposed a **Warning** under the intro of `api-keys.mdx`."
Product
Resources
Company
© 2026 SyntextBuilt with Syntext