Authentication

All API requests require an API key passed via the X-Api-Key header.

X-Api-Key: pk_live_...

API keys are bound to a specific expert and billed to the key owner's wallet. To request an API key, contact support .

Endpoint

Request

{
  "question": "What do you know about vitamin C?",
  "session_token": null
}

Success Response (200)

{
  "session_token": "3ab1aca5-6442-4456-81da-11b5f1ddceda",
  "answer": {
    "answer_text": "Vitamin C is a powerful antioxidant...",
    "answer_type": "directly_supported",
    "supported_points": [
      {
        "text": "Vitamin C boosts immunity",
        "evidence_refs": ["E1", "E3"]
      }
    ],
    "synthesis_points": [],
    "uncertainties": [],
    "citations": {
      "E1": {
        "source_title": "Video about vitamins",
        "source_type": "uploaded_video",
        "source_url": null,
        "passage_text": "Original transcript passage..."
      }
    }
  },
  "queries_remaining": 4,
  "limit_reached": false
}

Answer Types

Limit Reached Response (200)

{
  "session_token": "3ab1aca5-...",
  "limit_reached": true,
  "signup_url": "https://sagetube.ai/register",
  "message": "You've used your free questions. Create an account to continue."
}

Error Responses

All errors return {"error": "...", "message": "..."}

Sessions

• First request: Omit session_token or send null. The response includes a new token.
• Follow-up requests: Include the session_token from the previous response to maintain conversation context.
• Expiry: Sessions expire after 24 hours of inactivity (sliding window — resets on each query).
• Expired tokens: If you send an expired token, a new session is created automatically with a new token in the response.
• Free queries: Each session allows a limited number of free queries (default: 5). After the limit, the response includes limit_reached: true.

Rate Limits

• 30 requests per minute per IP address
• Maximum 3 new sessions per IP per 24-hour period
• Exceeding limits returns HTTP 429

Billing

Queries are billed to the API key owner's SageTube wallet at the standard pay-as-you-go rate. The owner must maintain sufficient wallet balance — if the balance reaches zero, the API returns HTTP 402.

Quick Start

First request — creates a new session:

curl -X POST https://sagetube.ai/api/public/expert/chat \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_live_your_key_here" \
  -d '{"question": "What is vitamin D good for?"}'

Follow-up request — uses the session token from the first response:

curl -X POST https://sagetube.ai/api/public/expert/chat \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pk_live_your_key_here" \
  -d '{"question": "Tell me more about dosage", "session_token": "3ab1aca5-6442-4456-81da-11b5f1ddceda"}'

Reference Implementation

andruid.ai is a working example of a thin-client integration:

• Laravel + Livewire frontend calls the API server-side via Guzzle
• API key stored in .env (never exposed to the browser)
• Session token persisted in an encrypted cookie
• Renders structured answers with expandable citation passages

Embeddable Chat Widget

Want a drop-in chat bubble instead? See the Chat Widget documentation — one script tag, no backend required.