API

Chat-Shares-API

Erstelle, liste, widerrufe oeffentliche Share-Links fuer Chat-Sessions.

Die Chat-Shares-API erlaubt es, AI-Chat-Sessions als oeffentlichen Read-only-Link zu teilen — z.B. fuer Kunden-Reviews oder als Beleg fuer eine Master-Agent-Analyse. Owner erstellt ueber /v1/chat-shares, der Empfaenger liest ueber /share/{token} (public, noindex). Volle Modul-Doku: Agentic Chat.

Alle API-Endpoints Sanctum-authentifiziert, team-scoped.

Endpoints

Method	Endpoint	Beschreibung
GET	`/v1/chat-shares`	Eigene Shares (paginiert 25/Seite)
POST	`/v1/chat-shares`	Neuen Share-Link fuer eigene Session erzeugen
GET	`/v1/chat-shares/{id}`	Detail + Stats
PATCH	`/v1/chat-shares/{id}`	Settings updaten (inkl. `freeze`)
DELETE	`/v1/chat-shares/{id}`	Widerrufen (Soft-Delete)
GET	`/v1/chat-shares/{id}/views`	Paginierter View-Log (DSGVO-anonymisiert)
GET	`/v1/agentic/sessions/{session}/shares`	Shares einer bestimmten Session

POST /v1/chat-shares

Body:

Feld	Pflicht	Default	Beschreibung
`session_id`	ja	—	ID einer `AiChatSession`, die dem User gehoert
`title`	nein	—	Titel fuer die Share-Page
`expires_at`	nein	+7 Tage	ISO-Datetime, muss in der Zukunft liegen
`password`	nein	—	min 4 Zeichen — aktiviert das Password-Gate
`max_views`	nein	—	Hard-Cap an einzigartigen Views (≥1)
`show_user_messages`	nein	`true`	User-Bubbles anzeigen
`show_assistant_messages`	nein	`true`	Assistant-Bubbles anzeigen
`show_tool_results`	nein	`false`	Tool-Call-Karten ein/aus — Empfaenger sieht sonst nur Inputs+Outputs
`show_reasoning_steps`	nein	`false`	Reasoning-/Thinking-Bloecke
`show_uploaded_files`	nein	`true`	Hochgeladene Files (Screenshots, PDFs)

Mindestens eine show_*-Option muss true sein, sonst liefert die API 422.

curl -X POST "$BASE/chat-shares" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "session_id": 42,
    "title": "Backlinks-Analyse fuer Kunde 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-Analyse fuer Kunde 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}

Akzeptiert dieselben Felder wie POST plus freeze: bool:

freeze: true — friert den Content-Snapshot ein. Spaetere Aenderungen an der Quell-Session sind im Share nicht mehr sichtbar.
freeze: false — zurueck auf live; Share spiegelt erneut die aktuelle Session.

DELETE /v1/chat-shares/{id}

Soft-Revoke. Setzt revoked_at — der Public-Link liefert ab sofort 410 Gone. Die Row bleibt 90 Tage in der DB (configurable via CHAT_SHARES_RETENTION_DAYS), dann loescht ein Daily-Prune-Job sie endgueltig.

Public Route (NICHT in der API)

Diese Routes leben nicht unter /api/v1/ — sie sind oeffentliches HTML:

Method	Pfad	Beschreibung
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) — setzt path-scoped httpOnly-Cookie
GET	`/share/{token}/print`	Print-CSS-Variante fuer PDF-Export

Statistik & View-Log

GET /v1/chat-shares/{id}/views liefert die DSGVO-anonymisierte View-Historie — IP-Hash, User-Agent-Family, Referrer-Domain, Timestamp. Keine personenbezogenen Daten.

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

Status-Codes

Code	Bedeutung
201	Share erstellt
200	List/Detail/Update/Views OK
204	DELETE erfolgreich
403	Session gehoert nicht dem User
404	Share oder Session nicht gefunden
410	Share widerrufen (nur public-route)
422	Keine `show_*`-Option `true`, ungueltiges `expires_at`, `password` zu kurz

Pitfalls

show_tool_results=false ist Default. Standardmaessig sieht der Empfaenger keine Tool-Call-Karten — nur die Konversation. Aktiv setzen, wenn du z.B. SERP-Daten oder Backlink-Tabellen mitteilen willst.
freeze ist nicht reversibel ohne PATCH. Einmal gefroren, bleibt der Snapshot stehen — auch wenn die Session weiterlaeuft.
Public-Link ist nicht widerrufbar via Token. Widerruf nur via DELETE /v1/chat-shares/{id} mit Auth-Token des Owners.
Password-Throttle ist hart. 6+ falsche Versuche / Minute → 429 fuer 60 s; ein zweiter Bypass-Versuch verlaengert das Lockout.

Verwandt: Agentic Chat · Agentic-Plans-API · Auth-API.

Letzte Aktualisierung: 1. Mai 2026