/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Share a Conversation

Share a Conversation

Share a doc-site reader's assistant conversation as a read-only link, or stop sharing it.

POST/v1/projects/{projectId}/chat/sessions/{sessionId}/shareTry it

Turns one of a reader's conversations into a read-only link, and takes the link back. On doc engine v2 sites with agent mode, this is Share in the /ask chat header and Share link in a conversation's menu. See Sharing.

Both endpoints are public (no API key required) and scoped to the project and the visitorId: only the reader who owns a conversation can share it or stop sharing it.

Note

On your doc site these endpoints are also served same-origin at /_chat/sessions/{sessionId}/share (POST, DELETE). The project comes from the site's hostname, so the path takes no projectId. Any other method gets 405 method_not_allowed, and a session ID that isn't a UUID gets 400 invalid_request before it reaches the API.

•
A snapshot. The link shows the messages written up to the moment it was shared. Messages added to the conversation later never appear in it.
•
The questions and answers only, at most 100 messages. A code block the reader attached is left out — only what they typed is shown. The reader's memory, visitor ID and votes are never included.
•
The same link every time. Sharing an already shared conversation returns the same token and snapshot, so a link already handed out never grows. To share newer messages, stop sharing and share again: that makes a new link.

The link is read at /ask/s/{token} on your doc site, which loads it from Get a Shared Conversation.

When sharing is refused

Refused whenCode
The project turned sharing off (aiPersona.sharing: "off")409 SHARING_DISABLED
The site is private — behind a password or SSO, or behind access control in password or invite-only mode409 SHARING_DISABLED
Any answer in the conversation used audience-gated content, or a code block attached on a page the reader opened with an audience token409 GATED_CONTENT
The conversation has no answers yet409 EMPTY_CONVERSATION

Answers given before 13 November 2026 weren't checked for gated content when they were written, so they count as gated: a conversation that contains one can't be shared.

Share

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.
sessionId:stringpathRequired
The conversation's UUID.

Request Body

NameDescription
visitorId:stringbodyRequired
The anonymous visitor identifier (1–100 chars) that owns the conversation.

Response — 200 OK

NameDescription
token:string
The share token: 32 random bytes, base64url-encoded (43 characters). Anyone with it can read the snapshot.
path:string
Where the link opens on your doc site. Prefix it with the site's origin, such as https://acme-docs.syntext.dev.
sharedAt:string
The time of the last message in the snapshot (ISO 8601).

Stop sharing

DELETE/v1/projects/{projectId}/chat/sessions/{sessionId}/share

The link stops working at once. Sharing the conversation again later creates a new link.

Query Parameters

NameDescription
visitorId:stringqueryRequired
The anonymous visitor identifier (1–100 chars) that owns the conversation.

Response — 200 OK

Also 200 when the conversation wasn't shared.

Rate Limits

Share has these limits; Stop sharing has none.

PerLimit
Visitor20 shares an hour
Client IP60 shares an hour — only for requests through your doc site
Project500 shares an hour

A request is only counted once the conversation is found to be the visitor's. Over a limit, the response is 429 with a Retry-After header — see Agent mode action limits.

Error Responses

StatusCodeWhen
400INVALID_REQUESTThe session ID isn't a UUID, or DELETE without a visitorId
400validation_errorPOST body without a valid visitorId
403FORBIDDENThe site is private (password, invite-only or SSO) and the request didn't come through the doc site ("Ask from the docs site")
404NOT_FOUNDThe project doesn't exist, or the conversation isn't this visitor's in this project
409SHARING_DISABLEDSharing is off for the project, or the site is private
409GATED_CONTENTAn answer used audience-gated content
409EMPTY_CONVERSATIONNothing to share yet
429RATE_LIMITEDA share limit was reached. retryAfterSeconds says when to try again
500internal_errorThe link could not be created or removed
•
Get a Shared Conversation — read the transcript behind a link
•
Conversation History — list, rename and delete a visitor's conversations
•
Sharing — what readers see
Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/chat/sessions/b2e9a1c4-5d3f-4e7a-9b08-6c2f1d4e8a93/share \
-H "Content-Type: application/json" \
-d '{ "visitorId": "vis_9f8e7d" }'
Responseapplication/json
200OK
{
"data": {
"token": "q3V9xZk2Lm8RtYp0aBcD4eFgH5iJ6kLmN7oPqR8sT9u",
"path": "/ask/s/q3V9xZk2Lm8RtYp0aBcD4eFgH5iJ6kLmN7oPqR8sT9u",
"sharedAt": "2026-11-13T15:02:41.118Z"
}
}
Responseapplication/json
200OK
{ "ok": true }
Product
Resources
Company
© 2026 SyntextBuilt with Syntext