Alfie REST API reference

GET/me#

Read your plan and remaining credits

Required scope: notes:read

curl "https://alfienotes.com/api/v1/me" \
  -H "Authorization: Bearer $ALFIE_API_KEY"

{
  "plan": "pro",
  "remaining_usage_seconds": 36000
}

Status codes

• 200 Plan and remaining credits.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 405 method_not_allowed.
• 429 rate_limited: too many requests for this key.
• 500 internal_error.

POST/uploads#

Get a pre-signed URL to upload a file

Required scope: notes:write

PUT the file bytes to upload_url with the required_headers before expires_at (10 minutes), then submit a job with type: "upload" and the upload_id. Files over 800 MB are rejected at job submission with validation_error. The job transcribes the bytes present when it is submitted; later PUTs to the same URL do not affect it.

Accepted formats. Uploads are charged by their real audio length, so only uncompressed WAV (PCM or IEEE float, RIFF/WAVE) is accepted: content_type must be audio/wav, audio/x-wav or audio/wave (other types get 400 validation_error with details.allowed), and a job whose file is not such a WAV fails with 422 unsupported_media. Convert other media to WAV first, for example ffmpeg -i in.m4a -ac 1 -ar 16000 out.wav. Compressed formats may be accepted again in a later version.

curl -X POST "https://alfienotes.com/api/v1/uploads" \
  -H "Authorization: Bearer $ALFIE_API_KEY" \
  -H "Idempotency-Key: lecture-week-1-upload" \
  -H "Content-Type: application/json" \
  -d '{"filename":"lecture-week-1.wav","content_type":"audio/wav"}'

{
  "upload_id": "YOUR_UPLOAD_ID",
  "upload_url": "https://storage.example.com/YOUR_UPLOAD_ID.wav?X-Amz-Signature=EXAMPLE",
  "expires_at": "2026-11-04T09:40:00.000Z",
  "required_headers": {
    "Content-Type": "audio/wav"
  }
}

Status codes

• 201 Upload URL created.
• 400 validation_error: the request is invalid.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 405 method_not_allowed.
• 409 idempotency_conflict: the key was used with a different request; or idempotency_in_progress: the first request is still running (see Retry-After).
• 429 rate_limited: too many requests for this key.
• 500 internal_error.

POST/jobs#

Submit an upload or a YouTube link for transcription

Required scope: notes:write

Credits for the media's duration are reserved atomically; a WAV is charged from its size, not its header. There is no refund if processing later fails (same as the web app). One item per request. Poll GET /jobs/{id} until status is succeeded or failed.

curl -X POST "https://alfienotes.com/api/v1/jobs" \
  -H "Authorization: Bearer $ALFIE_API_KEY" \
  -H "Idempotency-Key: lecture-week-1-job" \
  -H "Content-Type: application/json" \
  -d '{"type":"upload","upload_id":"YOUR_UPLOAD_ID","speaker_count":2,"language":"en"}'

{
  "job": {
    "id": "YOUR_NOTE_ID",
    "note_id": "YOUR_NOTE_ID",
    "status": "processing",
    "created_at": "2026-11-04T09:30:00.000Z"
  }
}

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"}'

{
  "job": {
    "id": "YOUR_NOTE_ID",
    "note_id": "YOUR_NOTE_ID",
    "status": "processing",
    "created_at": "2026-11-04T09:30:00.000Z"
  }
}

Status codes

• 202 Job accepted.
• 400 validation_error: the request is invalid.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 402 insufficient_credits: not enough remaining credits for this media.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 404 not_found: no such resource for this key's user (another user's id also returns 404).
• 405 method_not_allowed.
• 409 idempotency_conflict: the key was used with a different request; or idempotency_in_progress: the first request is still running (see Retry-After).
• 422 unsupported_media: the uploaded file is not in a format accepted right now (see POST /uploads). No credits were reserved.
• 429 rate_limited: too many requests for this key.
• 500 internal_error.

GET/jobs/{id}#

Poll a job

Required scope: notes:read

The job id is also the note id.

curl "https://alfienotes.com/api/v1/jobs/YOUR_NOTE_ID" \
  -H "Authorization: Bearer $ALFIE_API_KEY"

{
  "job": {
    "id": "YOUR_NOTE_ID",
    "note_id": "YOUR_NOTE_ID",
    "status": "succeeded",
    "created_at": "2026-11-04T09:30:00.000Z"
  }
}

Status codes

• 200 Job status.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 404 not_found: no such resource for this key's user (another user's id also returns 404).
• 405 method_not_allowed.
• 429 rate_limited: too many requests for this key.
• 500 internal_error.

GET/notes#

List your notes, newest first

Required scope: notes:read

Auto-deleted notes are excluded. Pass next_cursor back as cursor to get the next page.

curl "https://alfienotes.com/api/v1/notes?limit=1" \
  -H "Authorization: Bearer $ALFIE_API_KEY"

{
  "data": [
    {
      "id": "YOUR_NOTE_ID",
      "title": "lecture-week-1.wav",
      "status": "succeeded",
      "duration_seconds": 3120,
      "source": "file",
      "created_at": "2026-11-04T09:30:00.000Z",
      "is_public": false
    }
  ],
  "next_cursor": "eyJjIjoiMjAyNi0xMS0wNFQwOTozMDowMFoiLCJpIjoiWU9VUl9OT1RFX0lEIn0"
}

Status codes

• 200 A page of notes.
• 400 validation_error: the request is invalid.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 405 method_not_allowed.
• 429 rate_limited: too many requests for this key.
• 500 internal_error.

GET/notes/{id}#

Fetch a note with its transcript and latest summary

Required scope: notes:read

Another user's note returns 404.

curl "https://alfienotes.com/api/v1/notes/YOUR_NOTE_ID" \
  -H "Authorization: Bearer $ALFIE_API_KEY"

{
  "note": {
    "id": "YOUR_NOTE_ID",
    "title": "lecture-week-1.wav",
    "status": "succeeded",
    "duration_seconds": 3120,
    "source": "file",
    "created_at": "2026-11-04T09:30:00.000Z",
    "is_public": false,
    "region": "us",
    "transcribed_at": "2026-11-04T09:41:12.000Z",
    "transcript": [
      {
        "start": 0,
        "end": 4.2,
        "text": "Welcome back. Today is about eigenvalues.",
        "speaker": "Speaker 1"
      },
      {
        "start": 4.2,
        "end": 7.9,
        "text": "Will this be on the exam?",
        "speaker": "Speaker 2"
      }
    ],
    "artifact": null
  }
}

Status codes

• 200 The note.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 404 not_found: no such resource for this key's user (another user's id also returns 404).
• 405 method_not_allowed.
• 429 rate_limited: too many requests for this key.
• 500 internal_error.

PUT/notes/{id}/sharing#

Share or unshare a note

Required scope: notes:write

Idempotent: setting the current value again succeeds.

curl -X PUT "https://alfienotes.com/api/v1/notes/YOUR_NOTE_ID/sharing" \
  -H "Authorization: Bearer $ALFIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public":true}'

{
  "id": "YOUR_NOTE_ID",
  "is_public": true
}

Status codes

• 200 The new sharing state.
• 400 validation_error: the request is invalid.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 404 not_found: no such resource for this key's user (another user's id also returns 404).
• 405 method_not_allowed.
• 429 rate_limited: too many requests for this key.
• 500 internal_error.

GET/notes/{id}/export#

Export a transcript as plain text

Required scope: notes:read

One [hh:mm:ss] Speaker: text line per segment. Returns 400 validation_error when the note has no transcript yet.

curl "https://alfienotes.com/api/v1/notes/YOUR_NOTE_ID/export?format=txt" \
  -H "Authorization: Bearer $ALFIE_API_KEY"

[00:00:00] Speaker 1: Welcome back. Today is about eigenvalues.
[00:00:04] Speaker 2: Will this be on the exam?

Status codes

• 200 The transcript.
• 400 validation_error: the request is invalid.
• 401 unauthorized: the API key is missing, malformed, unknown or revoked.
• 403 insufficient_scope: the key lacks the required scope; or plan_limit: the media is longer than your plan allows.
• 404 not_found: no such resource for this key's user (another user's id also returns 404).
• 405 method_not_allowed.
• 429 rate_limited: too many requests for this key.
• 500 internal_error.