Read Voice Notes

List, search, filter, and retrieve notes and original recordings with the Public API.

All Notes endpoints use the base URL:

https://api.monologue.to/v1/public-api

List notes

GET /notes

The list response contains note metadata, summaries, and tags. Use the detail endpoint when you need the transcript or original recording. List responses do not include recording URLs.

Query parameter	Meaning
`limit`	Items per page. Defaults to 20; maximum 100.
`cursor`	Opaque `next_cursor` from the previous response.
`created_after`	Notes created after this ISO 8601 timestamp.
`created_before`	Notes created before this ISO 8601 timestamp.
`updated_after`	Notes updated after this ISO 8601 timestamp.
`q`	Searches title, summary, and transcript.
`tag_id`	Matches any supplied tag. Repeat the parameter for more than one tag.

curl --get "https://api.monologue.to/v1/public-api/notes" \
  --header "Authorization: Bearer $MONOLOGUE_API_TOKEN" \
  --data-urlencode "q=launch review" \
  --data-urlencode "created_after=2026-07-01T00:00:00Z" \
  --data-urlencode "limit=20"

Retrieve a note

GET /notes/{note_id}

The detail response includes transcript, transcript_segments, and recording details in addition to the fields returned by the list endpoint.

curl "https://api.monologue.to/v1/public-api/notes/$NOTE_ID" \
  --header "Authorization: Bearer $MONOLOGUE_API_TOKEN"

Only notes owned by the authenticated user are available. An unknown or inaccessible note returns 404.

Download the original recording

The single-note response includes these fields:

Field	Meaning
`recording_url`	Signed download URL for the original uploaded audio, valid for one hour.
`recording_url_expires_at`	UTC expiration timestamp for the URL.
`recording_content_type`	Recorded MIME type, or `null` when unavailable.
`recording_bytes`	Recorded file size in bytes, or `null` when unavailable.

Download the returned recording_url directly. Do not send your Monologue API token to the storage URL. This example uses jq to read the JSON response:

NOTE_JSON=$(curl --fail --silent --show-error \
  "https://api.monologue.to/v1/public-api/notes/$NOTE_ID" \
  --header "Authorization: Bearer $MONOLOGUE_API_TOKEN")
RECORDING_URL=$(printf '%s' "$NOTE_JSON" | jq --raw-output '.recording_url')
curl --fail --show-error "$RECORDING_URL" --output recording.m4a

Choose a filename extension that matches recording_content_type when available. Monologue returns the uploaded file in its existing format; it does not convert or enhance the audio for download. Recording access is available independently of transcription status, so a failed transcription does not prevent downloading an existing recording.

Refresh a recording URL

GET /notes/{note_id}/audio-url

Use the same personal API token with notes:read to request a fresh link without fetching the full note:

curl --fail "https://api.monologue.to/v1/public-api/notes/$NOTE_ID/audio-url" \
  --header "Authorization: Bearer $MONOLOGUE_API_TOKEN"

{
  "audio_url": "https://storage.example/recording.m4a?signature=example",
  "expires_in": 3600
}

audio_url points to the same recording as the detail response’s recording_url. expires_in is the URL lifetime in seconds. Fetching the full note again also produces a fresh link.

Treat signed URLs as secrets. Anyone holding a URL can download the recording until it expires, even after the API token that requested it is revoked. Save the note ID for future requests instead of treating the URL as a permanent link.

A signed URL does not verify that the stored file still exists. If a download fails because the URL expired, request a fresh link and retry. If the recording has been removed, refreshing the URL cannot restore it; the note’s text can still be retrieved.