API

API Chat Shares

Créer, lister, révoquer des liens publics de partage pour des sessions de chat.

L'API Chat Shares permet de partager des sessions de chat IA en lien public read-only — par ex. pour des reviews client ou comme preuve d'une analyse Master-Agent. Le owner crée via /v1/chat-shares, le destinataire lit via /share/{token} (public, noindex). Doc module complète : Agentic Chat.

Tous les endpoints API sont authentifiés Sanctum, team-scoped.

Endpoints

Méthode	Endpoint	Description
GET	`/v1/chat-shares`	Tes propres shares (paginé 25/page)
POST	`/v1/chat-shares`	Créer un nouveau lien de partage pour ta session
GET	`/v1/chat-shares/{id}`	Détail + stats
PATCH	`/v1/chat-shares/{id}`	Mettre à jour les paramètres (incl. `freeze`)
DELETE	`/v1/chat-shares/{id}`	Révoquer (soft-delete)
GET	`/v1/chat-shares/{id}/views`	Log de vues paginé (anonymisé RGPD)
GET	`/v1/agentic/sessions/{session}/shares`	Shares d'une session donnée

POST /v1/chat-shares

Body :

Champ	Obligatoire	Défaut	Description
`session_id`	oui	—	ID d'une `AiChatSession` appartenant à l'utilisateur
`title`	non	—	Titre de la page de share
`expires_at`	non	+7 jours	Datetime ISO, doit être dans le futur
`password`	non	—	min 4 caractères — active le password gate
`max_views`	non	—	Plafond strict de vues uniques (≥1)
`show_user_messages`	non	`true`	Afficher les bulles utilisateur
`show_assistant_messages`	non	`true`	Afficher les bulles assistant
`show_tool_results`	non	`false`	Cartes d'appels d'outils on/off — sinon le destinataire ne voit que inputs+outputs
`show_reasoning_steps`	non	`false`	Blocs reasoning/thinking
`show_uploaded_files`	non	`true`	Fichiers uploadés (screenshots, PDFs)

Au moins une option show_* doit être true, sinon l'API renvoie 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
  }'

Réponse 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}

Accepte les mêmes champs que POST plus freeze: bool :

freeze: true — gèle le snapshot de contenu. Les modifications ultérieures de la session source ne sont plus visibles dans le share.
freeze: false — repasse en live ; le share reflète à nouveau la session courante.

DELETE /v1/chat-shares/{id}

Soft-revoke. Définit revoked_at — le lien public renvoie immédiatement 410 Gone. La row reste 90 jours en DB (configurable via CHAT_SHARES_RETENTION_DAYS), puis un job de prune quotidien la supprime définitivement.

Route publique (PAS dans l'API)

Ces routes vivent hors de /api/v1/ — c'est du HTML public :

Méthode	Path	Description
GET	`/share/{token}`	Vue HTML read-only, `noindex` via meta + `X-Robots-Tag` + disallow `robots.txt`
POST	`/share/{token}/unlock`	Formulaire mot de passe (throttle 5/min) — pose un cookie httpOnly path-scoped
GET	`/share/{token}/print`	Variante print-CSS pour export PDF

Statistiques & log de vues

GET /v1/chat-shares/{id}/views fournit l'historique de vues anonymisé RGPD — hash d'IP, famille de user-agent, domaine de referrer, timestamp. Aucune donnée à caractère personnel.

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

Codes de statut

Code	Signification
201	Share créé
200	List/Detail/Update/Views OK
204	DELETE réussi
403	La session n'appartient pas à l'utilisateur
404	Share ou session introuvable
410	Share révoqué (route publique uniquement)
422	Aucune option `show_*` à `true`, `expires_at` invalide, `password` trop court

Pièges

show_tool_results=false est le défaut. Par défaut, le destinataire ne voit pas les cartes d'appels d'outils — seulement la conversation. Active-le si tu veux par exemple partager des données SERP ou des tableaux de backlinks.
freeze n'est pas réversible sans PATCH. Une fois gelé, le snapshot reste figé — même si la session continue.
Le lien public n'est pas révocable via le token. La révocation passe uniquement par DELETE /v1/chat-shares/{id} avec le token d'auth du owner.
Le throttle password est strict. 6+ tentatives erronées / minute → 429 pendant 60 s ; une seconde tentative de bypass prolonge le lockout.

Voir aussi : Agentic Chat · API Agentic Plans · API Auth.

Letzte Aktualisierung: 1 mai 2026