/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Page Presence

Page Presence

Tell Syntext you have a file open, see who else does, and leave when you close it.

POST/v1/projects/{projectId}/pages/{path}/presenceTry it
Session token

Presence shows who else has a file open in the editor. Opening a file with GET /pages/{path}/content records you automatically. While the file stays open, send a heartbeat with POST at least every 2 minutes. When you close it, send DELETE.

DELETE/v1/projects/{projectId}/pages/{path}/presence
Note

Any member of the workspace can call these, signed in with a session JWT — API keys are refused with 401. You must belong to the organization that owns {projectId}. Available on every plan. Neither call touches the repository.

Presence expires 120 seconds after your last content read or heartbeat, so a tab that closes without sending DELETE drops off on its own. Presence is best effort: when it is unavailable, editors is always empty and both calls still return 200.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.
path:stringpathRequired
The file path as you opened it, URL-encoded as one segment — e.g. guides%2Fquickstart.mdx.

Heartbeat — POST

Records that you have the file open, and returns the other people who do. You are never listed.

cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/pages/guides%2Fquickstart.mdx/presence \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response — 200 OK

Each editor's name is their display name, or the part of their email address before the @ if they have none. Full email addresses are never shown.

Leave — DELETE

Removes you from the file's editors.

cURL
curl -X DELETE https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/pages/guides%2Fquickstart.mdx/presence \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Error Responses

400 Bad Request

invalid_path — {path} is not valid URL encoding.

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.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl --request POST \
--url 'https://api.syntext.dev/v1/projects/{projectId}/pages/{path}/presence' \
--header 'Authorization: Bearer <jwt>'
Responseapplication/json
200OK
{
"data": {
"editors": [
{ "name": "Ada Lovelace" }
],
"ttlSeconds": 120
}
}
Responseapplication/json
200OK
{ "data": { "left": true } }
Product
Resources
Company
© 2026 SyntextBuilt with Syntext