Skip to content
alfiealfie
On this page

Alfie API & MCP docs

Send Alfie a lecture, talk or YouTube video and get back a timestamped transcript and notes. Use the REST API from any language, or connect an AI agent through the MCP server.

Get an API key#

  1. Sign in and open Settings → API keys.
  2. Create a key and choose Read only or Read & write. To submit recordings you need Read & write.
  3. Copy the key straight away. It is shown once and starts with alfie_. You can revoke it from the same page.

Keep the key in an environment variable, not in your code:

Shell
export ALFIE_API_KEY="alfie_YOUR_API_KEY"

Authentication & scopes#

Send the key as a bearer token on every request: Authorization: Bearer $ALFIE_API_KEY. The REST API lives at https://alfienotes.com/api/v1 and the MCP server at https://alfienotes.com/api/mcp. Both accept the same keys.

API key scopes
ScopeKey typeAllows
notes:readRead onlyRead credits, jobs, notes and transcripts.
notes:writeRead & writeAlso create uploads, submit jobs (spends credits) and change sharing.

A missing, unknown or revoked key gets 401 unauthorized. A key without the scope gets 403 insufficient_scope.

Quick start (curl)#

These four requests turn a YouTube video into a transcript, once you replace YOUR_VIDEO_ID and YOUR_NOTE_ID with real values.

  1. 1. Check the key works and see your credits

    curl
    curl "https://alfienotes.com/api/v1/me" \
  -H "Authorization: Bearer $ALFIE_API_KEY"
    JSON response · 200
    {
  "plan": "pro",
  "remaining_usage_seconds": 36000
}

  2. 2. Submit a YouTube video

    curl
    curl -X POST "https://alfienotes.com/api/v1/jobs" \
  -H "Authorization: Bearer $ALFIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"youtube","url":"https://www.youtube.com/watch?v=YOUR_VIDEO_ID"}'
    JSON response · 202
    {
  "job": {
    "id": "YOUR_NOTE_ID",
    "note_id": "YOUR_NOTE_ID",
    "status": "processing",
    "created_at": "2026-11-04T09:30:00.000Z"
  }
}

  3. 3. Poll until the job succeeds

    curl
    curl "https://alfienotes.com/api/v1/jobs/YOUR_NOTE_ID" \
  -H "Authorization: Bearer $ALFIE_API_KEY"
    JSON response · 200
    {
  "job": {
    "id": "YOUR_NOTE_ID",
    "note_id": "YOUR_NOTE_ID",
    "status": "succeeded",
    "created_at": "2026-11-04T09:30:00.000Z"
  }
}

  4. 4. Read the transcript

    curl
    curl "https://alfienotes.com/api/v1/notes/YOUR_NOTE_ID/export?format=txt" \
  -H "Authorization: Bearer $ALFIE_API_KEY"
    Text response · 200
    [00:00:00] Speaker 1: Welcome back. Today is about eigenvalues.
[00:00:04] Speaker 2: Will this be on the exam?

The job id is also the note id. Long recordings can take several minutes, so poll every 10–30 seconds.

Next steps#