---
title: "List notes"
method: GET
path: "/v1/notes"
tags: ["Notes"]
---

# List notes

`GET /v1/notes`

## Request

- Base URL: `https://api.blinq.me`
- URL: `https://api.blinq.me/v1/notes`
- Auth: HTTP bearer

Returns a paginated list of the authenticated user's note metadata.

Notes are sorted by creation time, newest first, unless `order_by` specifies update time. Ties are broken by note ID, so pages are deterministic.

For an initial sync, page with `order_by=updated_at` until `has_more` is `false`. For incremental syncs, record a checkpoint before each run, pass it as `updated_at_gte` (inclusive) with a small overlap, upsert by `id`, and advance the checkpoint only after every page succeeds.

Deleted notes are omitted. There is no deletion feed; periodically reconcile a complete list of IDs to detect removals. Timestamp filtering alone does not provide lossless synchronization.

Get an individual note to read its content.

Requires the `blinq:notes:read` scope.

## Query parameters

- `created_after` string, date-time
- `created_before` string, date-time
- `updated_at_gte` string, date-time
- `order_by` 'created_at' | 'updated_at'
- `cursor` string
- `limit` integer

## Response `200`

One page of note metadata.

- object: One page of note metadata.
  - `notes` object[], required: Note metadata for this page. Get an individual note to read its content.
    - `id` string, required: The ID of the note.
    - `title` string, nullable, required: The custom title set by the user, otherwise the generated title, or `null` when the note has neither.
    - `created_at` string, date-time, required: When the user's device created the note, as an ISO 8601 timestamp.
    - `updated_at` string, date-time, required: When the note was last updated, as an ISO 8601 timestamp.
    - `deleted_at` unknown, required
    - `status` 'processing' | 'ready' | 'failed' | 'blocked', required: The processing state of the note. `processing`: recording or processing is in progress. `ready`: no recording or processing is pending. Content may be empty or null. `failed`: processing failed. Partial content may be available. `blocked`: processing is blocked by the account plan or usage limits.
    - `type` 'voice_note' | 'phone_call' | 'text', nullable, required: How the note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note. `null` when the type is unavailable.
    - `share_url` string, nullable, required: A URL for viewing the note in a browser, or `null` when the note has no share link. Reading a note never creates a share link or changes sharing settings.
    - `linked_contacts` object[], required: The contacts linked to the note, or an empty array when there are none. Retrieving a linked contact requires `blinq:contacts:read` and contact access.
      - `id` string, required: The ID of the linked contact.
      - `full_name` string, nullable, required: The display name of the linked contact, or `null` when none is available.
      - `workspace_id` string, required: The personal workspace ID to pass when getting this contact.
  - `has_more` boolean, required: Whether another page of notes is available.
  - `next_cursor` string, nullable, required: The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`.
  - `total_count` integer, nullable, required: The total number of notes matching the filters. Returned on the first page; `null` on subsequent pages.

## Other responses

- `400`: Bad request - Invalid query parameters or body. See `details` for each failing field
- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation

---

[API](https://skmtc.dev/blinq/apis/blinq-public-api.md) - [All operations](https://skmtc.dev/blinq/apis/blinq-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/blinq/apis/blinq-public-api/revisions/2dedf4b14340?raw)