Labsco
intellectronica logo

monologue-notes-api

★ 277

by intellectronica · part of intellectronica/agent-skills

Use this skill when the user wants to read or search their Monologue notes through the Monologue Notes REST API. It covers authentication with the MONOLOGUE_API_KEY environment variable, safe token handling, listing notes, fetching a single note, pagination, filters, and error handling. The API is read-only and should be accessed with direct HTTP requests such as curl or any equivalent REST client.

🧩 One of 7 skills in the intellectronica/agent-skills package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Monologue Notes API

This skill provides the information needed to call the Monologue Notes REST API directly. Use it for read-only operations on the authenticated user's notes.

Use whatever HTTP client fits the task: curl, a short script, or another REST-capable tool. Do not invent client libraries unless the user asks for one.

Authentication

Use the environment variable MONOLOGUE_API_KEY as the bearer token.

  • Required auth header: Authorization: Bearer $MONOLOGUE_API_KEY
  • Required scope: notes:read
  • Never print the token, echo it, log it, or include it in a response to the user
  • Only pass it through the Authorization header as a shell variable expansion

Check whether the token is available without displaying it:

if [ -z "${MONOLOGUE_API_KEY:-}" ]; then
  echo "MONOLOGUE_API_KEY is not set"
fi

If MONOLOGUE_API_KEY is missing:

  • Report that the environment variable is not present
  • Ask the user whether they want to provide an API key
  • Do not attempt authenticated API calls until a token is available

Avoid commands such as these because they would expose secrets:

echo "$MONOLOGUE_API_KEY"
env | grep MONOLOGUE_API_KEY
set | grep MONOLOGUE_API_KEY

Base URL

  • Base URL: https://api.monologue.to
  • API shape: read-only Notes API
  • Data format: JSON
  • Timestamps: ISO 8601 date-time strings

Request Pattern

For all requests:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/..."

If structured output is useful, pipe the response to jq.

Endpoints

List notes

GET /v1/public-api/notes

Returns a page of notes for the authenticated user.

Supported query parameters:

  • limit: integer from 1 to 100, default 20
  • cursor: opaque pagination cursor from a previous response
  • created_after: ISO 8601 timestamp
  • created_before: ISO 8601 timestamp
  • updated_after: ISO 8601 timestamp
  • q: full-text search across titles, summaries, and transcripts

Example:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?limit=20&q=interview"

Example with jq:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?limit=20" \
  | jq '{next_cursor, items: [.items[] | {note_id, title, summary, created_at, updated_at}]}'

Expected response fields:

  • items: array of note summaries
  • next_cursor: cursor for the next page, if any

Each list item may include:

  • note_id
  • title
  • summary
  • created_at
  • updated_at

Possible errors:

  • 400: invalid filter or cursor
  • 401: missing or invalid token
  • 403: token lacks the required scope
  • 422: validation error

Get a single note

GET /v1/public-api/notes/{note_id}

Returns the full details for one note belonging to the authenticated user.

Path parameters:

  • note_id: note identifier returned by the list endpoint

Example:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes/NOTE_ID"

Example with jq:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes/NOTE_ID" \
  | jq '{note_id, title, summary, transcript, transcript_segments, created_at, updated_at}'

In addition to the list fields, the full note response may include:

  • transcript
  • transcript_segments

Notes:

  • transcript_segments is loosely typed structured JSON and may be null
  • 404 means the note was not found for the authenticated user

Possible errors:

  • 401: missing or invalid token
  • 403: token lacks the required scope
  • 404: note not found
  • 422: validation error

Common Workflows

Search notes by keyword

Use the q parameter:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?q=meeting"

Search covers:

  • note titles
  • note summaries
  • note transcripts

Page through results

  1. Call GET /v1/public-api/notes
  2. Read next_cursor from the response
  3. Pass that cursor back as the cursor query parameter
  4. Stop when next_cursor is absent or null

Example:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?limit=50&cursor=OPAQUE_CURSOR"

Filter by time

Use ISO 8601 date-time values:

curl -sS \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  "https://api.monologue.to/v1/public-api/notes?created_after=2026-01-01T00:00:00Z"

Operating Rules

  • Treat this API as read-only
  • Do not claim write support; this skill only covers listing and reading notes
  • Prefer https://api.monologue.to for requests
  • When reporting failures, summarise the HTTP status and relevant response body without exposing the token
  • If the user asks for a workflow that requires local post-processing, fetch the data first and then transform it separately

Source Notes

This skill is based on:

  • /Users/eleanor/repos/obsidian/intellectronica/2026-04-21-20-10 Monologue API.md
  • Live OpenAPI checks against https://api.monologue.to/public-openapi.json on 2026-04-22