Share a Conversation
Share a doc-site reader's assistant conversation as a read-only link, or stop sharing 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.
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.
What a link contains
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 when | Code |
|---|---|
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 mode | 409 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 token | 409 GATED_CONTENT |
| The conversation has no answers yet | 409 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
projectIdsessionIdRequest Body
visitorIdResponse — 200 OK
tokenpathhttps://acme-docs.syntext.dev.sharedAtStop sharing
/v1/projects/{projectId}/chat/sessions/{sessionId}/shareThe link stops working at once. Sharing the conversation again later creates a new link.
Query Parameters
visitorIdResponse — 200 OK
Also 200 when the conversation wasn't shared.
Rate Limits
Share has these limits; Stop sharing has none.
| Per | Limit |
|---|---|
| Visitor | 20 shares an hour |
| Client IP | 60 shares an hour — only for requests through your doc site |
| Project | 500 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
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | The session ID isn't a UUID, or DELETE without a visitorId |
| 400 | validation_error | POST body without a valid visitorId |
| 403 | FORBIDDEN | The site is private (password, invite-only or SSO) and the request didn't come through the doc site ("Ask from the docs site") |
| 404 | NOT_FOUND | The project doesn't exist, or the conversation isn't this visitor's in this project |
| 409 | SHARING_DISABLED | Sharing is off for the project, or the site is private |
| 409 | GATED_CONTENT | An answer used audience-gated content |
| 409 | EMPTY_CONVERSATION | Nothing to share yet |
| 429 | RATE_LIMITED | A share limit was reached. retryAfterSeconds says when to try again |
| 500 | internal_error | The link could not be created or removed |