API Reference

Internal REST API used by the Veractum frontend.

Rate Limits

Tier	Analyses / month	Max video length	Claims per analysis
Observer (free)	2	10 min	5
Analyst	30	1 hour	10
Veractor	Unlimited	6 hours	20

POST /api/analyze

Start a new analysis for a YouTube video. Requires authentication.

Request Body

{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "locale": "pt"   // optional, defaults to "en"
}

Success Response `202`

{
  "success": true,
  "data": {
    "analysisId": "cmo...",
    "status": "PROCESSING"
  }
}

Error Responses

401Not authenticated

402Monthly quota exceeded

422No captions available or transcript too short

503Database unavailable

GET /api/analyze

Poll the status of an analysis. Used by the results page to detect completion.

Query Parameters

GET /api/analyze?id=cmo...

Response when PROCESSING `200`

{
  "success": true,
  "data": {
    "id": "cmo...",
    "status": "PROCESSING",
    "claims": []
  }
}

Response when COMPLETE `200`

{
  "success": true,
  "data": {
    "id": "cmo...",
    "status": "COMPLETE",
    "videoTitle": "...",
    "summary": { "overview": "...", "keyPoints": [...], "segments": [...] },
    "claims": [
      {
        "id": "...",
        "text": "The claim text",
        "type": "FACTUAL",
        "status": "SUPPORTED",
        "confidence": 85,
        "reasoning": "...",
        "sources": [{ "title": "...", "url": "...", "domain": "..." }],
        "timestamp": "3:45"
      }
    ]
  }
}

Authentication

All endpoints require a valid NextAuth session cookie. Sign in via /api/auth/signin using Google OAuth. The session token is set automatically as an HTTP-only cookie.