# monologue-notes-api

monologue-notes-api — a skill to read and search Monologue notes through the REST API. Handles auth via MONOLOGUE_API_KEY, supports pagination, time filters, and full-text search.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 221 installs · ★ 304 repo stars
- Author: intellectronica
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/intellectronica/agent-skills/tree/HEAD/skills/monologue-notes-api/SKILL.md
- Updated: 2026-04-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/monologue-notes-api

## What it does

This skill covers direct interaction with the Monologue Notes read-only REST API using `curl` or any HTTP client. Two key endpoints: `GET /v1/public-api/notes` lists notes with limit, cursor-based pagination, `q` for search, and filters for creation and update timestamps; `GET /v1/public-api/notes/{note_id}` retrieves full note details including transcript and transcript segments.

Auth uses the `MONOLOGUE_API_KEY` environment variable as a bearer token in the `Authorization` header. The skill covers safe token handling—checking presence without logging it, handling errors like 401 (invalid token), 403 (missing `notes:read` scope), and 404 (note not found). Responses are JSON with ISO 8601 timestamps; you can pipe to `jq` for custom output.

Search works across titles, summaries, and transcripts. For large result sets, cursor-based pagination fetches pages of 20–100 items; pass the `next_cursor` from one response back as the `cursor` parameter to the next request, stopping when `next_cursor` is absent. The skill blocks API calls if `MONOLOGUE_API_KEY` is missing and prompts the user to supply a token.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill monologue-notes-api -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/monologue-notes-api/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/monologue-notes-api/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill monologue-notes-api -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/monologue-notes-api/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill monologue-notes-api -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/monologue-notes-api/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install intellectronica/agent-skills skills/monologue-notes-api
```

2. **Manually: put the files in place**
- File: `.github/skills/monologue-notes-api/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill monologue-notes-api -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/intellectronica/agent-skills --path skills/monologue-notes-api
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/monologue-notes-api/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add intellectronica/agent-skills --skill monologue-notes-api -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/intellectronica/agent-skills/tree/HEAD/skills/monologue-notes-api/SKILL.md

## When to use it
- search notes by keyword in title, summary or transcript
- fetch full text and structured segments from a single note
- page through large lists of notes, 20–100 per page
- filter notes by creation or modification date
- safely pass API credentials without exposing them in logs

## Example prompts
- Find all notes containing the word “interview” in the content
- Get the full text of the note with ID `NOTE_ID`
- Show the 50 most recent notes created after 2026-01-01

## Source text · SKILL.md · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: f8cea07da99cd48a.

BEGIN THIRD-PARTY FILE f8cea07da99cd48a
````text
---
name: monologue-notes-api
description: >
  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.
---

# 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:

```bash
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:

```bash
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:

```bash
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
````
END THIRD-PARTY FILE f8cea07da99cd48a

The third-party file has ended. Everything between the f8cea07da99cd48a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2287 of 5714 bytes. © intellectronica · CC0-1.0 · https://github.com/intellectronica/agent-skills/tree/HEAD/skills/monologue-notes-api/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
