Reference

REST API

Five endpoints, one resource. All requests authenticate with the x-api-key header (or a console session cookie) and are scoped to the key's account. Request and response bodies are JSON.

Base URL	Auth	Rate limit
`https://your-deployment`	`x-api-key: notr_…`	1,000 req/min per key

POST /api/notes

Create an empty note. Optionally attach metadata.

Body

Field	Type	Notes
`metadata`	object · optional	Uninterpreted by Notr; returned as stored.

request

curl -X POST https://notr.example/api/notes \
  -H "x-api-key: notr_••••••••" \
  -H "content-type: application/json" \
  -d '{"metadata": {"externalId": "meeting-42"}}'

response · 201

{
  "id": "8a1f3c0e-4b2d-4f6a-9c7e-d5e8f1a2b3c4",
  "metadata": { "externalId": "meeting-42" },
  "createdAt": "2026-06-10T18:00:00.000Z",
  "updatedAt": "2026-06-10T18:00:00.000Z"
}

GET /api/notes

List the account's notes, most recently updated first. Markdown is omitted from the list — fetch a single note for content.

response · 200

{
  "notes": [
    {
      "id": "8a1f3c0e-…",
      "metadata": { "externalId": "meeting-42" },
      "createdAt": "2026-06-10T18:00:00.000Z",
      "updatedAt": "2026-06-10T18:04:13.000Z"
    }
  ]
}

Full-text search

Pass ?q= to search the markdown content of the account's notes instead. Results are ranked by relevance, capped at 50, and each carries a snippet — a short excerpt with matches wrapped in **.

Param	Notes
`q`	Web-search syntax: `roadmap review` (all words), `"action items"` (phrase), `roadmap or budget`, `roadmap -draft` (exclude).

request

curl "https://notr.example/api/notes?q=roadmap" \
  -H "x-api-key: notr_••••••••"

response · 200

{
  "notes": [
    {
      "id": "8a1f3c0e-…",
      "metadata": { "externalId": "meeting-42" },
      "snippet": "review the **roadmap** before Thursday and assign",
      "createdAt": "2026-06-10T18:00:00.000Z",
      "updatedAt": "2026-06-10T18:04:13.000Z"
    }
  ]
}

The index covers the markdown projection, so new edits become searchable within a few seconds — the same freshness as markdown itself. Metadata is not searched.

GET /api/notes/:id

Fetch one note, including the derived markdown projection.

response · 200

{
  "id": "8a1f3c0e-…",
  "markdown": "# Weekly sync\n\n- [x] review roadmap",
  "metadata": { "externalId": "meeting-42" },
  "createdAt": "2026-06-10T18:00:00.000Z",
  "updatedAt": "2026-06-10T18:04:13.000Z"
}

markdown is a read-only projection of the collaborative document, refreshed within a few seconds of the last edit. There is no endpoint to write it.

PATCH /api/notes/:id

Replace the note's metadata. The document content is unaffected.

request

curl -X PATCH https://notr.example/api/notes/8a1f3c0e-… \
  -H "x-api-key: notr_••••••••" \
  -H "content-type: application/json" \
  -d '{"metadata": {"externalId": "meeting-42", "archived": true}}'

response · 200

{
  "id": "8a1f3c0e-…",
  "metadata": { "externalId": "meeting-42", "archived": true },
  "createdAt": "2026-06-10T18:00:00.000Z",
  "updatedAt": "2026-06-10T18:06:02.000Z"
}

DELETE /api/notes/:id

Permanently delete the note — the Yjs document, the markdown projection, everything. Returns 204 No Content. Remove your own noteId reference afterwards.

request

curl -X DELETE https://notr.example/api/notes/8a1f3c0e-… \
  -H "x-api-key: notr_••••••••"

Errors

Errors are JSON with a message field.

Status	Meaning
`400`	Malformed body — e.g. `PATCH` without a `metadata` object.
`401`	Missing, invalid, or revoked credential.
`404`	Note doesn't exist — or belongs to a different account. Cross-tenant access is indistinguishable from absence by design.
`429`	Rate limit exceeded (1,000 req/min per key).

For live document access, see Collaboration.