The API

Potion's HTTP API lets your own scripts and services read and write a workspace: capture a note, log a record, pull data back out. You generate a key in Settings, send it with each request, and the key acts as you.

It is not the same thing as the MCP, which connects an AI assistant to your workspace. This is for code you write, and it reaches every object a workspace holds: notes, records and structures, tags, properties, presets, views, graph lenses, Quick Access and files.

This page is also available as plain Markdown at /docs/api.md.

The whole API is described as OpenAPI 3.1 at api.potion.run/openapi.json. Import it into Postman, Insomnia or Bruno to try every endpoint with your key, or generate a client from it.

Every call goes to https://api.potion.run/v1/….

Keys

A key is created in Settings → API keys, and shown once. Potion stores a hash of it, never the key, so a lost key cannot be recovered — make another and revoke the old one.

Two things are fixed when a key is made:

• One workspace. A key reaches exactly one workspace and can never see another, which keeps a leaked key as contained as the workspace boundary itself.
• Read or write. A read-only key is refused on every write with a message saying so. Use one for anything that only pulls data.

A key never grants more than you have. It resolves to your account, and the database applies the same rules it applies to the app: your notes, your workspace, trashed notes excluded.

Making a request

Authorization: Bearer potion_sk_xxxxxxxx

Send JSON, receive JSON.

curl https://api.potion.run/v1/me \
  -H "Authorization: Bearer potion_sk_xxxxxxxx"

{
  "user_id": "1037…",
  "workspace_id": "4f91d444-…",
  "key": { "id": "33e5…", "name": "logging script", "scope": "write" }
}

Start here when something is not working: /v1/me tells you which workspace the key opens and whether it may write. GET /v1/workspace names that workspace and counts what is in it.

Notes

Every list answers with total and has_more, so a count on your side always matches what you actually received.

Three ways to write, and when to use each

This is the part worth reading twice. Most APIs give you one way to change a document, and it is the dangerous one.

• Append adds to the end without reading the note first. Nothing already there can be lost. Reach for it by default when you are adding.
• Edit replaces one exact passage. If the passage appears twice, or not at all, the call is refused rather than guessing. Reach for it to change something specific.
• PATCH replaces the whole body. Use it last. Send if_unchanged with the updated_at you read, and the call is refused if anything changed in between.

Why it matters: a note's body carries [[wiki links]] that hold a note's id, potion:layout directives and share pins. Regenerating a whole body, especially through a language model, is how those quietly break. The narrow shapes exist so you rarely have to.

curl -X POST https://api.potion.run/v1/notes/$ID/append \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"text":"- shipped the importer","heading":"2026-09-22"}'

Deleting is always soft. A note goes to the trash, where it stays recoverable for 30 days. The API has no permanent delete.

Properties are strict: a key the workspace does not define, or a value that does not fit its type, refuses the whole call and nothing is written. On POST /v1/notes the note is still created, and the refusal comes back as properties_error.

History and the trash

A restored note gets its links back. Its Quick Access pin does not come back, and it keeps its alias only if no other note claimed it in the meantime.

Records

Records are rows of a structure, not notes: a weight on a date, an expense, a logged reading. A record cannot exist before its structure, so declare the structure first.

A batch is one transaction. If any row is refused, nothing is written and the error names the row, so a retry is safe.

curl -X POST https://api.potion.run/v1/records \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"structure":"weight","data":{"kg":81.6,"when":"2026-09-22"}}'

Name a structure by its id in anything long-lived. A name stops matching the day you rename the structure; an id never changes.

Every row carries created_at and updated_at, set by the database and never by a caller. When the day something happened matters, give the structure a date field and fill it.

max_rows: 1 makes a settings object: a write replaces the one row (the previous one is kept, deleted). max_rows: N caps a list, refusing the row past N. Lowering it below the rows held is refused.

immutable: true makes rows facts: they can be written and deleted, never edited — a PATCH to one, or on_conflict: "update", is refused. Turning it on or off is always allowed.

Field changes are additive once rows exist: add fields, relabel them, hide them, but never remove, retype or rename a key. fields replaces the list, yet a field you resend without unique, unit, label, hidden, min or max keeps what it had. Deleting a structure is done in the app.

Filters

filter is a JSON list of conditions, all of which must hold:

filter=[{"field":"kg","op":"gte","value":80}]

Each kind of field answers its own operators, and anything else is refused rather than ignored:

A refused filter is a feature: a dropped condition would quietly widen your answer, and every total built on it would be wrong. neq and not_in also match rows that have no value at all. On created_at and updated_at — set only by the database, never by a caller — a plain date means that whole day.

Watching live

GET /v1/records/watch asks the same question as GET /v1/records and keeps the connection open: it answers now, then again every time the structure changes, from any surface. It is Server-Sent Events, not a WebSocket, so curl -N reads it line by line, and a read-only key is enough.

curl -N -H "Authorization: Bearer $POTION_API_KEY" \
  "https://api.potion.run/v1/records/watch?structure=inbox&sort=created_at&direction=desc&limit=5&changes=true"

event: answer
data: {"structure":{…},"records":[…],"total":12,"has_more":true}

: alive

event: answer
data: {"structure":{…},"records":[…],"total":13,"has_more":true,"changes":{"created":[{…}],"updated":[],"removed":[]}}

• event: answer carries the whole page each time; with changes=true, each answer after the first also names the rows created, updated or removed since the previous one, so you need not compare pages yourself. "Removed" means the row left the page: deleted, filtered out, or pushed past limit by newer rows.
• : alive arrives every 25 seconds so a proxy does not close a quiet connection.
• event: problem reports one answer that failed; the stream stays open. event: closed means the key was revoked or expired, and the stream ends.
• Changes a few hundred milliseconds apart arrive as one answer. Reconnect when the connection drops; the first answer tells you where things stand.

Use a watch when your program runs somewhere a webhook cannot reach, such as a laptop or a terminal. Use a webhook when you have a public URL and want every event delivered even while you are away.

Webhooks

A structure can call a URL of yours whenever a matching row is written — created, updated or deleted, from any surface. Subscriptions are managed here like any other resource; receiving them (what arrives, the signature, retries) is its own page: Webhooks.

Tags

Renaming is always safe: views and lenses hold a tag's id, not its name. Deleting is refused (409) while a view filters on the tag or a graph lens is scoped by it, and the message names them. Otherwise that view would quietly start matching more notes.

Properties

A property is a typed value a note can carry: text, number, date, bool, select (with options), or json.

A type can change only while no note holds a value. Narrowing a select's options leaves values already on notes in place and lists them back as stranded_values. A delete is refused (409) while a view, preset or graph lens uses the property.

Presets

A preset is a named set of tags and property values written onto a note. A value can be fixed, or asked for (ask), with or without a pre-filled answer.

Applying adds and never takes away. A value the note already holds is kept unless you send overwrite: true. A question with no answer and no pre-filled value is left unset and listed in properties_unanswered. An empty value is never written.

Views

A view is a saved filter, a sort and what its cards show, re-evaluated whenever it is read.

sort is { "field": "created_at" | "updated_at" | "title" | "property", "direction": "asc" | "desc", "property": "rating" }, with property only for a property sort.

The filter tree

A filter is one tree of groups and conditions. It names tags by id and properties by definition id, as the app stores it, so take the ids from GET /v1/tags and GET /v1/properties.

{
  "type": "group", "match": "all",
  "children": [
    { "type": "tags", "op": "has_any", "tag_ids": [12, 40] },
    { "type": "property", "def_id": "9b1c…", "op": "gte", "value": 8 },
    { "type": "group", "match": "none", "children": [
      { "type": "field", "field": "title", "op": "contains", "value": "draft" }
    ] }
  ]
}

• Groups match all, any or none, and nest up to 4 deep, with at most 50 conditions.
• Tags take has_all, has_any or has_none.
• Properties take the operators of their type:
  • text and select: eq, neq, contains, not_contains, starts_with, ends_with, in, not_in, empty, not_empty
  • number: eq, neq, gt, gte, lt, lte, between
  • date: on, before, after, on_or_before, on_or_after, between, within
  • yes/no: eq
  • json: has_key, contains
  • every type: empty, not_empty
• Fields are title, created_at and updated_at.
• Dates take YYYY-MM-DD, or { "relative": { "n": 7, "unit": "day" } }.

The database checks every tree before saving it, and a tree it cannot answer is refused with the reason. The same tree drives POST /v1/notes/query and a graph lens's scope. Filters are described in full at /docs/filters.

Graph

The graph page opens on a lens, a saved way of looking at it: which notes (scope, a filter tree, or null for the whole workspace) and how to draw them (settings).

settings is { "layers": { "links", "tags" }, "nodes": { "orphans", "dangling" }, "look": { "arrows", "titles": "zoom" | "always" | "never" } }, all yes/no except titles.

Quick Access

The notes pinned to the sidebar, in order.

Files

Files, as readable text: attached to a note, or kept in the workspace alone. Uploading and deleting are done in the app.

A file's text is ready once its status is ready. A long text comes back with truncated: true and next_chunk, so ask for the next page range.

When something is refused

{ "error": "filter on \"created_at\" takes eq, neq, gt, gte, lt or lte, not \"in\"", "code": "refused" }

Refusals quote the rule that stopped the write, in the same words the app uses.

What this version does not do

These are deliberately left out, because each is either one wide, irreversible cascade or machinery that lives in the app:

• renaming or deleting a workspace
• deleting a structure
• deleting a note for good
• uploading or deleting a file
• layouts