Session Sharing API

Create shareable links to agent sessions. Sessions can be shared publicly (anyone with the link) or with specific users.

Overview

Session sharing generates a unique share token for a given session. Shares expire after a configurable TTL (default 7 days). Public shares do not require authentication to view. The session share data is stored in Mnesia and cleaned hourly by the event compactor.

Authentication

Create and delete operations require Authorization: Bearer <token>. Viewing a public share does not require authentication.

Endpoints

Create Share

POST /api/v1/sessions/:id/share

Request Body:

{
  "ttl_days": 7,
  "public": true,
  "label": "Q4 Demo"
}

Response:

{
  "ok": true,
  "data": {
    "token": "shr-xyz789",
    "session_id": "a1b2c3d4e5f6",
    "url": "https://nonsense.ws/share/shr-xyz789",
    "expires_at": 1746204800,
    "public": true,
    "label": "Q4 Demo"
  }
}

Get Share Details

GET /api/v1/sessions/:id/share/:token

Returns share metadata without the session content. Requires authentication if the share is private.

View Shared Session

GET /api/v1/share/:token

Public endpoint that returns the shared session content (messages, metadata). No authentication required for public shares.

{
  "ok": true,
  "data": {
    "session_id": "a1b2c3d4e5f6",
    "model": "claude-sonnet-4-20250514",
    "mode": "build",
    "message_count": 24,
    "messages": [
      {
        "role": "user",
        "content": "Explain quicksort",
        "timestamp": 1745600000
      }
    ]
  }
}

Delete Share

DELETE /api/v1/sessions/:id/share/:token

Removes a share. Only the session owner or an admin can delete shares.

{
  "ok": true
}

List Sessions

GET /api/v1/chat

Active sessions for the authenticated user. Admin users see all.

Share Limits:

Limit	Value
Max share size	1 MB
Default TTL	7 days
Max TTL	30 days
Public shares	Anybody with token can view

Error Codes:

Code	Description
401	Authentication required for create/delete
403	Not the session owner
404	Session or share not found
413	Session exceeds max share size

Examples:

curl -X POST http://127.0.0.1:11434/api/v1/sessions/a1b2c3d4e5f6/share \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl_days": 7, "public": true}'

curl http://127.0.0.1:11434/api/v1/share/shr-xyz789

curl -X DELETE http://127.0.0.1:11434/api/v1/sessions/a1b2c3d4e5f6/share/shr-xyz789 \
  -H "Authorization: Bearer $TOKEN"