Developers

Last updated 15 October 2026

Zimoma has a small JSON API and an MCP connector. With them, other apps, scripts and AI assistants such as Claude and ChatGPT can search and read your notes, write new ones, add to them, and work with your tasks and collections.

In short. Make a token in Zimoma › Settings › Connections. Send it as Authorization: Bearer zm_… to https://api.zimoma.com/v1/api. AI assistants connect to https://api.zimoma.com/mcp.

Tokens

Make one per app or assistant. Give it a name you will recognise, and choose Read only or Read & write.
It is shown once. Zimoma keeps only a fingerprint of it, so a lost token can’t be shown again. Make a new one instead.
Revoke it at any time in Settings › Connections. It stops working at once. Closing your account revokes every token.
It sees what you see. Your own notes, and the notes and collections in spaces you are in. In a space, your role there still applies: if you can only view a space, a token can only read it.
Keep it private. Anyone who has it can do what it allows.

Connect an AI assistant

The connector speaks the Model Context Protocol over Streamable HTTP. When you make a token, Zimoma also gives you a connector address: https://api.zimoma.com/mcp/ followed by the token. Use it where an app takes only an address. It holds the token, so keep it as private as the token.

Claude

In Claude, open Settings › Connectors › Add custom connector. Name it Zimoma and paste the connector address.

ChatGPT

Turn on developer mode (Settings › Connectors › Advanced), then create a connector. Paste the connector address and choose no authentication.

Claude Code and other apps that take a header

claude mcp add --transport http zimoma https://api.zimoma.com/mcp \
  --header "Authorization: Bearer zm_your_token"

Any MCP client can connect the same way: POST JSON-RPC to https://api.zimoma.com/mcp with the token in the Authorization header. The connector keeps no session and answers each request with JSON.

Tools

A read-only token is offered only the tools that read.

Tool	What it does
`search_notes`	Notes containing every word of a query, titles first.
`list_recent_notes`	The notes edited most recently.
`read_note`	One note as Markdown, with its title, link and your role.
`list_tasks`	Open or done tasks across your notes, or in one note.
`list_collections`	Your collections, with their fields.
`list_records`	A collection’s records, values by field name.
`list_spaces`	The shared spaces you are in.
`create_note`	A new note from Markdown, on its own or in a space.
`append_to_note`	Markdown added at the end of a note.
`add_task`	A task in your Tasks note or another note, with a day and time if you like.
`complete_task`	Ticks a task off. A repeating task comes back on its next day.
`add_record`	A new record in a collection.

The API

Every request goes to https://api.zimoma.com/v1/api with Authorization: Bearer zm_…. Bodies are JSON, up to 1 MB. Times come back in ISO 8601, in UTC.

curl https://api.zimoma.com/v1/api/me \
  -H "Authorization: Bearer $ZIMOMA_TOKEN"

Each token may make 120 requests a minute. Every answer says how many are left in X-RateLimit-Remaining. Over the limit, the answer is 429 with Retry-After in seconds.

Notes

Request	What it does
`GET /notes?limit=20&before=…`	Notes edited most recently, newest first. Pass the last note’s `updatedAt` as `before` for the next page.
`GET /notes/search?q=…&limit=20`	Notes with every word of `q`, with a snippet around the match.
`GET /notes/{id}`	One note: `title`, `markdown`, `html`, `updatedAt`, `url`, `access` and `version`.
`POST /notes`	`{ "title", "markdown", "spaceId" }`, all optional but one of the first two. Makes a note.
`POST /notes/{id}/append`	`{ "markdown" }`. Adds it at the end of the note.
`GET /spaces`	The shared spaces you are in, with your role in each.

curl https://api.zimoma.com/v1/api/notes \
  -H "Authorization: Bearer $ZIMOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Kyoto trip","markdown":"Book the **ryokan**.\n\n- [ ] Rail pass\n- [ ] Flights"}'

A note is changed on top of its latest version, as the apps change it, so nothing written on a phone at the same moment is lost. Everything you change appears on your devices within seconds, and for the people the note is shared with.

Markdown

Notes are written and read as Markdown: headings, paragraphs, bold, italic, strikethrough, inline code, links, bullet and numbered lists (nested too), task lists (- [ ] and - [x]), quotes, code blocks, horizontal rules and tables. HTML in the Markdown is kept as text. Links work for https:, mailto: and tel: addresses; pictures become links to the picture.

Tasks

Request	What it does
`GET /tasks?status=open&noteId=…&tz=…`	Tasks across your notes, or in one note. `status` is `open` (the default), `done` or `all`.
`POST /tasks`	`{ "text", "day", "time", "deadline", "noteId", "tz" }`. Only `text` is needed.
`POST /tasks/complete`	`{ "noteId", "index", "text" }`, as a task in the list gives them.

A task is a checklist item in a note. New tasks go to your Tasks note unless you give a noteId. A day (2026-10-20) and time (17:00) are written after the task as Zimoma writes them (“Call Rhea · 20 Oct, 5:00 PM”), and your devices remind you. With "deadline": true the day is when it is due by. Words such as “every Monday” make a task repeat.

Each task in the list has noteId, index (its place among the note’s open tasks) and text, plus title, due ({ "day", "time" }), deadline, repeat, done and doneOn. Pass tz, such as Europe/London, so that “today” and words like “tomorrow” mean your day. Without it they mean the day in UTC.

curl https://api.zimoma.com/v1/api/tasks \
  -H "Authorization: Bearer $ZIMOMA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Renew passport","day":"2026-10-20","time":"17:00"}'

Collections

Request	What it does
`GET /collections`	Your collections, with their fields, a select field’s options, and how many records each has.
`GET /collections/{id}/records?limit=100&offset=0`	Records in the collection’s order, values by field name.
`POST /collections/{id}/records`	`{ "values": { "Name": "Circe", "Status": "To read" } }`. Adds a record at the end.

Values are text, numbers, true or false for a checkbox, an option’s name for a select, and YYYY-MM-DD for a date.

Errors

A request that doesn’t work answers with a status and a plain sentence saying why:

{ "error": { "code": "forbidden", "message": "This token can only read.", "retryable": false } }

400 invalid: Something in the request is missing or isn’t valid.
401 unauthenticated: No token, or one that was revoked.
403 forbidden: A read-only token tried to change something, or you can only view that note or space.
404 not_found: There’s no such note, task or collection that you can see.
409 conflict: The note kept changing while it was being saved. Try again.
429 rate_limited: Too many requests. Wait for the seconds in Retry-After.

Contact

Questions, or something you would like the API to do: support@zimoma.com.