Cloud Notes API and webhooks
Let your own scripts and other services read and change your synced Cloud Notes: add a row to a database from a form or a shop, pull a page into a website, or get told when a page or a row changes. It's part of MyCloudSuites Plus.
What it reaches
- The notes you sync with Plus: the files in your Cloud Notes folder in your MyCloudSuites files.
- Pages other people share with you, with the role they gave you (view, comment, edit or full access).
- A note that lives only on one computer isn't synced, so the API can't reach it.
- Locked notes are sealed on your device. The API sees only that a note is locked: it never reads or changes one, and webhooks say nothing about it.
Changes go into the same files sync uses, so your devices pick them up on their next sync, and anyone with the page open live is told it changed.
Tokens
Make a token on your account page, under Developer. Each token has a name, what it may do (read, or read and write), and which pages: all of Cloud Notes, or one page with its sub-pages and rows. You can have up to 20.
- A token is shown once, when you make it. Afterwards only its last four characters are shown. We keep only a fingerprint of it, so we can't show it to you again: if you lose it, make another.
- Revoke a token on the account page at any time. It stops working at once. Each token shows when it was last used.
- Send it in the
Authorizationheader. Never put it in an address: such requests are refused. - If your Plus ends, your tokens can still read for 90 days while your files are kept, but can't change anything.
export MCS_NOTES_TOKEN=mcs_pat_... # keep it secret, like a password
curl -s -H "Authorization: Bearer $MCS_NOTES_TOKEN" https://mycloudsuites.com/api/v1/notes/pages
The API takes a token only. It never uses your sign-in, and it sends no CORS headers: call it from a server or a script, not from a web page, where the token would be visible to anyone.
Limits
Each token may make 60 calls a minute and 5,000 a day (the day is UTC). Past that, the answer is 429 with a Retry-After header saying how many seconds to wait.
Pages
| Call | What it does |
|---|---|
GET /api/v1/notes/pages?q=&in=&limit=&offset= | Pages your token reaches. q matches the title or path; in is a folder's or page's id, for what's directly in it (a page's sub-pages and rows). Up to 200 at a time (100 unless you say). |
GET /api/v1/notes/pages/:id | One page: its Markdown, as the file is written, and its version. |
PUT /api/v1/notes/pages/:id | { "markdown": "...", "base": "<version>" } replaces the page. If it changed since the version you read, the answer is 409 with { "conflict": true, "version": "<the latest>" }: read it again and retry. |
POST /api/v1/notes/pages | { "title": "...", "markdown": "...", "in": "<id>" } makes a page. in is a folder in Cloud Notes, or a page (the new page is its sub-page); without it the page goes at the top of Cloud Notes. A token for one page needs in. The page starts with # Title unless your Markdown already has a heading. |
A page answers as { id, title, path, version, updatedAt, database, locked, role, shared }, and markdown too when you ask for one page. A page can be up to 2 MB of text.
curl -s -H "Authorization: Bearer $MCS_NOTES_TOKEN" https://mycloudsuites.com/api/v1/notes/pages/PAGE_ID
curl -s -X PUT -H "Authorization: Bearer $MCS_NOTES_TOKEN" -H 'content-type: application/json' \
https://mycloudsuites.com/api/v1/notes/pages/PAGE_ID -d '{"markdown":"# Menu\n\nSoup of the day.\n","base":"VERSION"}'
Databases
A database page's rows are the pages in the folder named after it, beside it. Their values are kept at the top of each row's file, and typed by the database's properties.
| Call | What it does |
|---|---|
GET /api/v1/notes/databases/:id/rows?filter=&sort= | The rows, up to 1,000: { database: { id, title, properties }, rows: [{ id, title, version, updatedAt, locked, values }], more }. filter=Status:Baking keeps rows whose value matches (repeat it for more than one); sort=Qty or sort=-Qty sorts them (empty values last). |
POST /api/v1/notes/databases/:id/rows | { "values": { "Name": "Lin", "Status": "Baking" } } adds a row. It needs its title property. |
PATCH /api/v1/notes/databases/:id/rows/:row | { "values": { ... }, "base": "<version>" } changes those values and keeps the rest of the row. base is optional; with it, a row changed since is a 409. null clears a value. |
Values come back as: text, email, phone, URL and status as text; number as a number; checkbox as true or false; multi-select, person and files as lists; a relation as a list of row titles; a date as { "start": "2026-12-01", "end"?: "…", "remind"?: true }; created and last edited times as text. Formulas, rollups and buttons are worked out in Cloud Notes, so they aren't sent.
What you send is checked the way an answer to a shared form is: a select's or status's value must be one of its choices, a multi-select's a list of them, a number a number, a date YYYY-MM-DD, an email or web address one that looks right, a checkbox true or false, and text one line. Title, text, number, select, status, multi-select, date, checkbox, email, phone and URL properties can be set; others can't. A problem answers 400 with { "error": "...", "errors": { "Status": "Pick one of the choices." } }.
curl -s -H "Authorization: Bearer $MCS_NOTES_TOKEN" -H 'content-type: application/json' \
https://mycloudsuites.com/api/v1/notes/databases/PAGE_ID/rows -d '{"values":{"Name":"Lin","Status":"Ordered","Qty":2}}'
Errors
Errors are JSON, { "error": "..." }: 400 something sent is wrong; 401 no token, or an unknown or revoked one (a sign-in cookie alone is refused); 402 Plus is needed (or has ended, for a change); 403 the token or your role on the page can't do that; 404 the page isn't there, or the token can't reach it; 409 it changed since your base; 413 too long; 423 the note is locked; 429 too many calls.
Webhooks
Add a webhook on your account page, under Developer: an https address, the events to send, and for which pages (all, or one page with its sub-pages and rows). You can have up to 10. The address must be a public server's name on the standard https port, without a user name or password; addresses that are IP numbers or point inside a private network are refused.
| Event | When |
|---|---|
page.changed | A page was saved, from any device, app or this API. Saves within 10 seconds of the first are sent as one. |
row.added | A row was added to a database. |
row.changed | A row was saved. |
Each delivery is a POST of JSON. It never holds a page's whole text:
{ "id": "…", "event": "row.added", "at": "2026-11-13T12:00:22.000Z",
"page": { "id": "…", "title": "Winter orders" },
"row": { "id": "…", "title": "Lin", "values": { "Status": "Baking", "Qty": 2 } } }
With these headers:
MCS-Signature: t=<unix seconds>,v1=<signature>: the signature is the hex HMAC-SHA256 oft, a dot, and the body exactly as sent, keyed with the webhook's secret (shown once, when you add it, startingwhsec_).MCS-Event: the event.MCS-Delivery: the delivery's id, the same on every retry, so you can skip one you've had.
Check the signature before trusting a delivery, and refuse one whose t is more than five minutes old:
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(secret, header, body) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
const want = Buffer.from(createHmac('sha256', secret).update(`${parts.t}.${body}`).digest('hex'))
const got = Buffer.from(parts.v1 ?? '')
return want.length === got.length && timingSafeEqual(want, got)
}
Answer with any 2xx within 10 seconds. Anything else, no answer, or a redirect (redirects aren't followed) is tried again after 1, 5 and 30 minutes, 2 hours, and then every 6 hours, with a last try a day after the first. The account page lists each webhook's last 50 tries: when, how long they took, and the status your server answered (never the body). Send a test sends a ping event now.