Chat Shares API

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

POST /v1/chat-shares

Body:

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:

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

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.