API

Chat Shares API

Create, list, and revoke public share links for chat sessions.

The chat shares API lets you share AI chat sessions as a public read-only link — for example for customer reviews or as evidence of a master-agent analysis. The owner creates via /v1/chat-shares, the recipient reads via /share/{token} (public, noindex). Full module documentation: Agentic Chat.

All API endpoints are Sanctum-authenticated and team-scoped.

Endpoints

Method	Endpoint	Description
GET	`/v1/chat-shares`	Own shares (paginated 25/page)
POST	`/v1/chat-shares`	Create new share link for own session
GET	`/v1/chat-shares/{id}`	Detail + stats
PATCH	`/v1/chat-shares/{id}`	Update settings (including `freeze`)
DELETE	`/v1/chat-shares/{id}`	Revoke (soft-delete)
GET	`/v1/chat-shares/{id}/views`	Paginated view log (GDPR-anonymized)
GET	`/v1/agentic/sessions/{session}/shares`	Shares of a specific session

POST /v1/chat-shares

Body:

Field	Required	Default	Description
`session_id`	yes	—	ID of an `AiChatSession` owned by the user
`title`	no	—	Title for the share page
`expires_at`	no	+7 days	ISO datetime, must be in the future
`password`	no	—	min 4 chars — activates the password gate
`max_views`	no	—	Hard cap on unique views (≥1)
`show_user_messages`	no	`true`	Show user bubbles
`show_assistant_messages`	no	`true`	Show assistant bubbles
`show_tool_results`	no	`false`	Toggle tool-call cards — recipient otherwise sees only inputs+outputs
`show_reasoning_steps`	no	`false`	Reasoning/thinking blocks
`show_uploaded_files`	no	`true`	Uploaded files (screenshots, PDFs)

At least one show_* option must be true, otherwise the API returns 422.

curl -X POST "$BASE/chat-shares" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "session_id": 42,
    "title": "Backlinks analysis for customer X",
    "expires_at": "2026-06-01T00:00:00Z",
    "show_tool_results": true
  }'

Response 201:

{
  "data": {
    "id": 1,
    "token": "f3a9b2c4...",
    "url": "https://rankion.ai/share/f3a9b2c4...",
    "title": "Backlinks analysis for customer X",
    "session_id": 42,
    "expires_at": "2026-06-01T00:00:00Z",
    "frozen_at": null,
    "has_password": false,
    "max_views": null,
    "view_count": 0,
    "unique_viewer_count": 0,
    "last_viewed_at": null,
    "revoked_at": null,
    "status": "active",
    "show_user_messages": true,
    "show_assistant_messages": true,
    "show_tool_results": true,
    "created_at": "2026-05-01T09:14:01Z"
  }
}

PATCH /v1/chat-shares/{id}

Accepts the same fields as POST plus freeze: bool:

freeze: true — freezes the content snapshot. Later changes to the source session are no longer visible in the share.
freeze: false — back to live; share again mirrors the current session.

DELETE /v1/chat-shares/{id}

Soft-revoke. Sets revoked_at — the public link returns 410 Gone from then on. The row stays in the DB for 90 days (configurable via CHAT_SHARES_RETENTION_DAYS), then a daily prune job deletes it permanently.

Public route (NOT in the API)

These routes do not live under /api/v1/ — they are public HTML:

Method	Path	Description
GET	`/share/{token}`	Read-only HTML view, `noindex` via meta + `X-Robots-Tag` + `robots.txt` disallow
POST	`/share/{token}/unlock`	Password form (throttle 5/min) — sets a path-scoped httpOnly cookie
GET	`/share/{token}/print`	Print-CSS variant for PDF export

Stats & view log

GET /v1/chat-shares/{id}/views returns the GDPR-anonymized view history — IP hash, user-agent family, referrer domain, timestamp. No personally identifiable data.

curl "$BASE/chat-shares/1/views?per_page=50" \
  -H "Authorization: Bearer $TOKEN" | jq '.data[] | {viewed_at, ua_family, referrer_domain}'

Status codes

Code	Meaning
201	Share created
200	List/detail/update/views OK
204	DELETE successful
403	Session does not belong to the user
404	Share or session not found
410	Share revoked (public route only)
422	No `show_*` option `true`, invalid `expires_at`, password too short

Pitfalls

show_tool_results=false is the default. By default the recipient sees no tool-call cards — just the conversation. Set it explicitly when you want to share, for example, SERP data or backlink tables.
freeze is not reversible without PATCH. Once frozen, the snapshot stays — even if the session continues.
Public link cannot be revoked via token. Revocation only via DELETE /v1/chat-shares/{id} with the owner's auth token.
Password throttle is hard. 6+ wrong attempts/minute → 429 for 60 s; a second bypass attempt extends the lockout.

Related: Agentic Chat · Agentic Plans API · Auth API.

Letzte Aktualisierung: May 1, 2026