API Documentation

{
  "id": 42,
  "userId": "user_123",
  "filename": "report.pdf",
  "status": "processing",
  "conversationDate": null,
  "notes": null,
  "createdAt": "2025-03-15T10:30:45.123Z"
}

{
  "error": "No file uploaded. Send as multipart/form-data with field name 'file'"
}

{ "message": "Invalid API key" }

{ "message": "API key does not have the required scope: documents:write" }

{
  "error": "Monthly upload limit reached",
  "message": "You've reached the 60-document monthly limit. Resets on 2026-05-15T00:00:00.000Z.",
  "monthlyUploadLimit": 60,
  "monthlyUploadResetAt": "2026-05-15T00:00:00.000Z",
  "plan": "pro"
}

{
  "message": "Rate limit exceeded",
  "retryAfterMs": 5000
}

{ "error": "Failed to upload document" }

{
  "id": 42,
  "filename": "Standup notes.txt",
  "status": "processing",
  "createdAt": "2025-03-15T10:30:45.123Z"
}

{ "error": "Filename and content (or pdfBase64 for PDFs) required" }

{ "message": "Invalid API key" }

{
  "error": "Monthly upload limit reached",
  "message": "You've reached the 60-document monthly limit.",
  "monthlyUploadLimit": 60,
  "plan": "pro"
}

{ "message": "Rate limit exceeded", "retryAfterMs": 5000 }

{
  "id": 42,
  "filename": "the-state-of-ai-agents.html",
  "status": "processing"
}

{ "error": "The page returned too little readable text — it may be paywalled, login-only, or rendered entirely in JavaScript." }

{ "message": "Invalid API key" }

{
  "error": "Monthly upload limit reached",
  "message": "You've reached the 60-document monthly limit.",
  "monthlyUploadLimit": 60,
  "plan": "pro"
}

{
  "message": "URL submission rate limit exceeded — 20 per 5 min.",
  "retryAfterMs": 247000
}

event: connected
data: {"videoId":"Wia0oSOu7ZQ","canonicalUrl":"https://www.youtube.com/watch?v=Wia0oSOu7ZQ"}

event: fetching_youtube
data: { ... }

event: resolving_speakers
data: { ... }

event: speakers_resolved
data: {
  "method": "channel_memory+signals",
  "proposals": [
    { "label": "Speaker 2", "name": "Alex Hormozi", "role": "host", "confidence": 0.94 }
  ],
  "signals": [ ... ]
}

# transcript_created carries the transcriptId + the file's name.
# 'queued' here is a boolean that mirrors whether another upload is
# already ingesting (true) or this one will run inline (false).
event: transcript_created
data: { "transcriptId": 712, "filename": "...Wia0oSOu7ZQ.txt", "queued": false }

# persisted carries the youtube_sources row id + speaker resolution
# status — these are NOT on transcript_created.
event: persisted
data: { "youtubeSourceId": 5, "resolutionStatus": "pending" }

# When another upload is already ingesting, the handler emits 'queued'
# (with transcriptId again) and ends the stream; the sidecar picks the
# job up later. Otherwise progress / complete events stream from the
# sidecar inline.
event: queued
data: { "transcriptId": 712, "status": "queued", "message": "Queued — will be processed when current ingestion completes." }

# 'error' is emitted on failure;
# 'duplicate' (with transcriptId + youtubeSourceId) on dedup-hit retry path.

{
  "status": "exists",
  "message": "This video is already in your brain.",
  "videoId": "Wia0oSOu7ZQ",
  "transcriptId": 712,
  "youtubeSourceId": 5,
  "title": "The Only Way to Learn Skills That Matter",
  "channelName": "MoreMozi",
  "publishedAt": "2026-05-15T01:00:22.000Z",
  "createdAt": "2026-05-15T06:30:34.100Z"
}

{ "error": "url is required" }

{ "message": "Invalid API key" }

{
  "error": "Monthly upload limit reached",
  "message": "You've reached the 60-document monthly limit.",
  "monthlyUploadLimit": 60,
  "plan": "pro"
}

{
  "message": "YouTube submission rate limit exceeded — 20 per 5 min.",
  "retryAfterMs": 247000
}

event: error
data: { "error": "Failed to fetch video metadata from ScrapeCreators." }

{
  "transcript": {
    "id": 42,
    "filename": "report.pdf",
    "status": "processing",
    "notes": null,
    "conversationDate": null,
    "createdAt": "2025-03-15T10:30:45.123Z"
  },
  "analysis": null
}

{
  "transcript": { "id": 42, "filename": "report.pdf", "status": "analyzed", ... },
  "analysis": { "entities": [ ... ], "facts": [ ... ] }
}

{ "error": "Authentication required" }

{ "error": "Document not found" }

{
  "results": [
    {
      "fact": "Alice promised Bob a follow-up on March 15",
      "score": 0.87,
      "sourceEntity": { "name": "Alice", "type": "person" },
      "targetEntity": { "name": "Bob", "type": "person" },
      "date": "2025-03-15T00:00:00Z"
    }
  ],
  "totalResults": 1,
  "query": "what did I promise Sarah last week?"
}

{ "error": "query is required" }

{ "message": "Invalid API key" }

{ "error": "Missing scope: brain:read" }

{ "error": "Rate limit exceeded", "scope": "brain:read", "limit": 200 }

{
  "found": true,
  "uuid": "ent_abc123",
  "name": "Sarah Chen",
  "type": "person",
  "role": "PM",
  "organization": "Acme",
  "summary": "..."
}

{
  "found": false,
  "reason": "ambiguous",
  "message": "Multiple entities matching \"Sarah\" found.",
  "matches": [
    { "uuid": "ent_1", "name": "Sarah Chen", "type": "person" },
    { "uuid": "ent_2", "name": "Sarah Johnson", "type": "person" }
  ]
}

{
  "found": false,
  "reason": "not_found",
  "message": "No entity named \"Sarah Chen\" found in your knowledge graph."
}

{ "error": "name query parameter is required" }

{ "message": "Invalid API key" }

{ "error": "Missing scope: brain:read" }