Ezo API

Ezo API

Ezo's HTTP API reads and changes your lists, items and notes from your own code. It answers in JSON at one address, with a token you create in Settings, and keeps your plan's limits. The Ezo CLI is built on it.

Address

https://ezo.gs/api/v1

Every path on this page follows it: GET /me is https://ezo.gs/api/v1/me. In Settings, API access → Copy API URL copies the address.

Tokens

In Settings, open API access and choose Create. Name the token, choose read only or read and write, name the lists it may reach by their Ezo IDs if it should reach only some, and choose 30, 90 or 365 days. Copy the token before you leave the page: Ezo shows it once. Revoke stops it at once.

Send the token with every request:

curl https://ezo.gs/api/v1/me \
  -H "Authorization: Bearer $EZO_TOKEN"

The API works on every plan, and each request keeps the account's plan limits. A token is 256 random bits and Ezo keeps only its SHA-256 hash; revocation and expiry are checked on every request. A list ID alone grants nothing. A token kept to some lists cannot create lists or reach another list through an item ID.

Read only gives a token every read scope; read and write gives it all of them.

lists:read
Lists, folders, saved views, sharing and templates
lists:write
Creating, renaming, archiving and deleting lists; folders, views, sharing and publishing templates
items:read
Items and their notes, images, the calendar and .ezo exports
items:write
Creating, changing, moving and deleting items; .ezo imports and copying templates
preferences:read
Theme, language, accent and name display
preferences:write
Changing them

Lists and items

GET /me
The account, its plan, what it may use and the token in use
GET /lists
A page of your lists, then the lists shared with you
POST /lists
Create a list: { title, maxColumns? }
GET /lists/:id
One list
PATCH /lists/:id
Rename it, change its width, archive or restore it: { title?, maxColumns?, archived? }
DELETE /lists/:id
Remove the list
GET /lists/:id/items
A page of the list's items
POST /lists/:id/items
Create an item: { title, type?, content?, starred?, position?, date?, completedAt? }
GET /items/:id
One item with its note
PATCH /items/:id
Change it: { title?, type?, content?, starred?, completed?, archived?, position?, date? }
DELETE /items/:id
Delete the item
POST /items/:id/move
Move it to an empty place: { listId, position: { column, row } }
POST /items/move
Move up to 100 items together, making room: { itemIds, listId, position }
GET / PATCH /preferences
Read or change theme, language, accent colour and name display

An item's type is item, header, calc or text, and content is its note, up to 200,000 characters; a title holds up to 2,000. Positions count columns and rows from zero: a column within the list's width, and rows up to 999. A move keeps the item's ID, note and image.

date keeps when something happened or is due on the item rather than in its title: 2026-10-08, or 2026-10-08 14:30 with the hour it started. The calendar stands the item on that day, and null in a change takes it away. completedAt, an ISO time that has passed, records something done before it was written down: the item arrives complete and stays in its list until it is archived.

Example:

curl https://ezo.gs/api/v1/lists/12abcd/items \
  -H "Authorization: Bearer $EZO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bring-water-1" \
  -d '{"title":"Bring water"}'

Pages of results

Collections take limit (1 to 100, 50 if not given), cursor and archived=true. An answer is { data, nextCursor }; pass nextCursor back as cursor until it is null. A page may be empty and still have a cursor. Complete items stay in their list until they are archived.

Writes and retries

Every write needs an Idempotency-Key header of 8 to 128 letters, digits or . _ : -. For 24 hours a token and key name one request: sending it again returns the first result, and the same key with other input returns 409 idempotency_conflict. Each write and its record commit together, and an error leaves nothing half done. Keep the key and the body when you retry after an uncertain result.

Errors

An error is { "error": { "code", "message" }, "requestId" }.

400
The input is invalid
401
The token is missing, revoked or expired
403
The token's scope or the account's plan does not allow it (plan_required)
404
No such list or item, or not yours to see
409
The place is taken, the list is full (limit_reached), or the key was used with other input
413
The body is over 1 MB
415
The body is not JSON
429
Too many requests
500
Ezo failed

Answers are never cached. Browsers on other sites are refused: call the API from a server, a script or an app.

Notes, links and images

GET / POST /items/:id/mentions
The lists and items a note mentions / add one: { reference: { type, id } }
POST /items/:id/url/refresh
Fetch a link item's title and icon again, at most every 30 seconds
POST /lists/:id/images
Add a picture: { data, name, column?, row? }
GET / POST / DELETE /items/:id/image
The picture's address / replace it: { data } / remove it, keeping the item

A link item keeps its address as its title and carries urlPreview, which is pending, ready or failed; read the item again after a refresh. A picture's data is a WebP in base64, at most 2 MB; the CLI makes one from any photo.

.ezo files

GET /lists/:id/ezo returns the list as a .ezo file, { name, text }: CSV whose cells are Markdown, with each item's note and board under it. POST /lists/:id/ezo takes { text }, places the file below what the list holds, and returns the new top-level item IDs and how many items it added. Stars, notes, boards and calculations in a file need the plan that has them.

Calendar, folders and views

GET /calendar
Every item with a date in its title, note or date
GET / POST /folders
Home's folders / make one: { listIds, name? }
PATCH / DELETE /folders/:id
Rename it or move lists in and out: { name?, add?, remove? } / remove it
GET / POST /views
Saved side-by-side views / save one: { listIds }, two or three lists
DELETE /views/:id
Remove a saved view

A calendar date is { year, month, day }, with year null when the item names none; place it in the nearest year. A time written in the item comes as time, HH:MM. A folder made without a name is named by Ezo from what its lists hold. A list added to a folder leaves any other, a folder left empty is gone, and removing a folder leaves its lists on Home. Folder writes need a token that reaches every list.

Sharing

GET /lists/:id/sharing
The list's members and invitations, for its owner
POST /lists/:id/sharing
Invite one account: { recipientId, role, token, days? }
PATCH /lists/:id/sharing/members/:memberId
{ role }: viewer, editor or remove
DELETE /lists/:id/sharing/invitations/:invitationId
Withdraw an invitation
DELETE /lists/:id/sharing
Leave a list shared with you
POST /invitations/preview
See an invitation: { token }
POST /invitations/accept
Accept it: { token }

An invitation's token is 64 random lowercase hexadecimal characters that you make; Ezo keeps only its hash. It is for one account and one use, and lasts 1 to 30 days, 7 if not given. Keep tokens out of addresses. A viewer can read a list and an editor can change what it holds; only the owner renames, archives or deletes it, or manages who is on it. Working on a list together needs Plus.

Templates

GET /templates
The published templates, or yours with mine=true
GET /templates/:id
One template's content, at version= or its latest
GET /lists/:id/template-preview
What a list of yours would publish, with its sourceHash
POST /templates
Publish it: { listId, title, description, sourceHash, requestId, templateId? }
POST /templates/:id/copy
Copy it into a new list, or into listId: { version, listId?, requestId }
DELETE /templates/:id
Unpublish every version; copies stay

Publishing needs Plus or Agentic and takes exactly what the preview showed: if the list changed, preview it again. Only titles, notes, types, stars, positions and pictures are published, and your name and Ezo ID are shown with the template. Keep the same requestId and input when you retry.

Signing in from a terminal

A tool can ask for a token without anyone copying one. It makes a token itself and sends its name and an eight-character code to POST /auth/device; the person opens https://ezo.gs/connect/CODE, signs in, compares the code and chooses Connect. The tool asks POST /auth/device/poll with the same token until it is let in. A request lasts ten minutes and is approved once; the token lasts 90 days. DELETE /auth/token revokes the token in use.

AI apps

Claude, ChatGPT, Codex, Cursor and Notion connect to Ezo at https://ezo.gs/mcp, an MCP server that signs in with OAuth, so no token is copied. It needs Agentic. See Connect an AI app .