API Reference

The Narrative Lion API lets you programmatically access your notes, run searches, submit jobs, chat with AI, and more. Use it with Claude Code, Cursor, or any AI agent that speaks HTTP.

https://api.narrativelion.com

Most read/write operations are available via GraphQL at POST /graphql. Billing, audio streaming, and file exports use dedicated REST endpoints. Chat uses SSE.

Already using Claude Code, Cursor, Codex, or another AI agent? Install the Narrative Lion skill so your agent knows how to call this API for you.

npx skills add rayjan0114/narrative-lion-skills

Auto-detects your AI tool and installs to the right location. Run the same command anytime to pull the latest version.

After install, set your API key in your shell:

export NL_API_KEY=nlk_your_api_key_here

Source: github.com/rayjan0114/narrative-lion-skills

All API requests require an API key sent as a Bearer token in the Authorization header.

curl https://api.narrativelion.com/api/export/jobs \
  -H "Authorization: Bearer nlk_your_api_key_here"

API keys are available on the Pro and Business plans. Create one in Settings → API Keys.

Each key has a set of scopes that control what it can access. Keys are prefixed with nlk_ for easy identification.

REST endpoints handle billing, binary streaming, and file operations that are not suited for GraphQL.

{
  "tier": "pro",
  "period": "month",
  "resetsAt": "2026-05-21T00:00:00.000Z",
  "credits": {
    "used": 20,
    "limit": 3600,
    "remaining": 3580
  },
  "wallet": {
    "balance": 0,
    "enabled": false
  }
}

curl -X POST https://api.narrativelion.com/api/export/request \
  -H "Authorization: Bearer nlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"format": "markdown"}'

{
  "jobs": [
    {
      "id": "job-456",
      "status": "completed",
      "format": "markdown",
      "createdAt": "2026-04-20T10:00:00.000Z"
    }
  ]
}

The GraphQL endpoint is at POST /graphql. Send a JSON body with query and optional variables.

curl https://api.narrativelion.com/graphql \
  -H "Authorization: Bearer nlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ me { id email name } }"
  }'

Queries

query {
  jobs(status: queued, limit: 10) {
    id
    url
    status
    createdAt
  }
}

query {
  myNotes(limit: 20) {
    id
    videoId
    noteType
    lang
    noteMd
    tags
    updatedAt
  }
}

query {
  note(noteId: "abc-123") {
    id
    videoId
    noteType
    lang
    title
    noteMd
    tags
    starredAt
    createdAt
    updatedAt
  }
}

query {
  note(noteId: "abc-123") {
    id
    noteMd
    transcriptAvailable
    transcriptBytes
    rawTranscript    # only fetched when selected
  }
}

query {
  browseNotes(noteType: "video", starred: true, sort: "updated", limit: 10) {
    id
    noteMd
    starredAt
    tags
  }
}

query {
  search(query: "machine learning fundamentals", limit: 5) {
    id
    videoId
    title
    noteMd
    score
  }
}

query {
  ftsSearch(query: "transformer architecture", limit: 10) {
    id
    videoId
    noteType
    snippet
    rank
  }
}

Mutations

mutation {
  submitJob(url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ") {
    id
    status
    createdAt
  }
}

mutation {
  createGeneralNote(content: "# My Notes\n\nSome content here...") {
    id
    noteMd
    createdAt
  }
}

mutation {
  updateNote(noteId: "abc-123", noteMd: "# Updated content") {
    id
    version
    updatedAt
  }
}

mutation {
  deleteNote(noteId: "abc-123")
}

mutation {
  toggleStar(noteId: "abc-123") {
    id
    starredAt
  }
}

mutation {
  addTag(noteId: "abc-123", tag: "important") {
    id
    tags
  }
}

The chat endpoint uses Server-Sent Events (SSE) for streaming responses. Send a POST request and read the event stream.

curl -N https://api.narrativelion.com/api/chat/stream \
  -H "Authorization: Bearer nlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "thread-uuid",
    "actionId": "action-uuid",
    "event": {
      "type": "user_text",
      "payload": { "text": "Summarize my latest note" }
    }
  }'

event: token
data: {"t":"Hello"}

event: token
data: {"t":" world"}

event: complete
data: {"messageId":"msg-123","usage":{"inputTokens":150,"outputTokens":42}}

Each API key has a set of scopes that determine what operations it can perform. When creating a key, choose a preset or customize individual scopes.

Read preset includes: notes:read, search, jobs:read, billing:read.
Standard preset includes all Read scopes plus: notes:write, jobs:submit, chat, podcast, export.

The API returns errors as JSON with an error field and an optional code field.

{
  "error": "Credit limit reached (120/100). Resets 2026-05-21",
  "code": "QUOTA_EXCEEDED"
}

Rate limits are applied per account. If you exceed the limit, the API returns a 429 status.