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/v1Every 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
.ezoexports items:write- Creating, changing, moving and deleting items;
.ezoimports 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,editororremove- 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
.