REST API

MemNote has a REST API over your notes, tags, and devices. Both the hosted and local MCP servers are thin wrappers around it, so anything an assistant can do, your own script can do too.

https://api.memnote.randomfact.com

https://memnote.randomfact.com serves the same API, so either host works.

Interactive reference

The API describes itself. Browsable docs are at /docs, and the machine-readable OpenAPI 3.1 document is at /docs/json — point a code generator or an HTTP client at it and you get the current surface, always in step with what is deployed.

The lists below are a summary; /docs is the authority on field names and response shapes.

Authentication

Every request carries a bearer token:

Authorization: Bearer <access-token>

Tokens come from MemNote’s OAuth 2.0 authorization-code flow with PKCE. The endpoints are advertised at https://api.memnote.randomfact.com/.well-known/oauth-authorization-server, so a standard OAuth client can discover them rather than hard-coding anything. The pieces:

Endpoint	Purpose
POST /oauth/register	Register your client and get a client ID (dynamic client registration)
GET /oauth/authorize	Send the user to sign in and approve access
POST /oauth/token	Exchange the authorization code, and later refresh
POST /oauth/revoke	Revoke a token

Access tokens last 30 days and refresh tokens 90 days, so request offline_access if you want your integration to keep working unattended.

There is no personal access token to copy from the app. A user always authenticates in a browser with the same Google, Apple, or email sign-in they use in MemNote. If you would rather not implement OAuth yourself, use the local MCP server, which already handles the whole flow.

Client registration is rate limited to 30 registrations per IP address per hour.

Permissions

There is one scope, notes, and it covers reading and writing notes, tags, and devices. There is no read-only mode today, and no way to grant access to a subset of your notes.

Access is strictly per-user: a token can only ever reach the notes of the account that signed in to issue it.

Notes

Method	Path	What it does
GET	/v1/notes	List notes, most recently updated first. limit (1–100, default 20), pageToken, includeDeleted
POST	/v1/notes	Create a note. content is required; title, tags, and metadata (latitude, longitude, device) are optional
GET	/v1/notes/search	Semantic search. q required, limit 1–20 (default 10)
GET	/v1/notes/{id}	Read one note with its tags
PUT	/v1/notes/{id}	Update a note
DELETE	/v1/notes/{id}	Move a note to trash
GET	/v1/notes/{id}/history	Archived versions, newest first
POST	/v1/notes/{id}/tags/{tagId}	Add an existing tag to a note
DELETE	/v1/notes/{id}/tags/{tagId}	Remove a tag from a note

Behaviour worth knowing before you write against it:

• Search is meaning-based, not literal. /v1/notes/search ranks notes by how close they are in meaning to q and drops weak matches, so an unrelated query returns an empty list rather than a low-quality one. Each result carries a similarity score. If you need substring matching, list and filter yourself.
• PUT archives before it writes. The version you are replacing is kept and is readable from /v1/notes/{id}/history, and restorable in the app’s version history. An edit is never unrecoverable.
• PUT with tags replaces the whole tag set on that note. To add or remove one tag, use the tag sub-resources instead.
• DELETE is a soft delete. The note lands in Trash and syncs to your devices as deleted. The API has no permanent delete — that only happens from the app.
• Creating a note accepts tags by name and creates any that do not exist yet, and the same for the device name in metadata.
• Notes you create through the API sync down to your devices like any other note. Supplying latitude and longitude gets the note a place name too — see Context capture.

Tags

Method	Path	What it does
GET	/v1/tags	List your tags
POST	/v1/tags	Create a tag. name required; color and parentId optional
GET	/v1/tags/{id}	Read one tag
PUT	/v1/tags/{id}	Update a tag
DELETE	/v1/tags/{id}	Soft-delete a tag. Existing note associations are left alone

color is an index into MemNote’s tag palette, not a hex value. parentId makes a tag a child of another, which is what produces the nested tag tree in the app.

Devices

Method	Path	What it does
GET	/v1/devices	List your devices
POST	/v1/devices	Register a device. name and platform required
GET	/v1/devices/{id}	Read one device
PUT	/v1/devices/{id}	Update a device, e.g. rename it

Only GET /v1/devices is exposed by the hosted MCP server; the write operations are available over the API and from the local MCP server.

Conventions

• Request and response bodies are JSON.
• Errors come back as { "error": "<message>" } with the matching HTTP status. A missing or expired token is 401.
• DELETE returns 204 with no body.
• List endpoints that paginate return a nextPageToken; pass it back as pageToken to continue.
• Deletes across the API are soft (deletedAt is set) so they can sync and be undone.

Related

• Hosted MCP server — this API, exposed to AI assistants with no setup.
• Local MCP server — the same, run on your machine.