---
name: notesocket
description: Write to a NoteSocket note from code: add a line, tick a checklist item, set a table cell, change a live's Now line, move slides, run a countdown, go live. Use when an agent or script should update a note that people read, present or stream.
---

# NoteSocket

NoteSocket is a rich-text notepad for Windows whose notes sync to their own link. A note can be shared as a public page, presented as slides, or streamed live as you type. The developer API writes to the synced notes of one account, and the app and every open page follow within seconds.

## When to use it

- Use it to keep a note up to date from somewhere else: scores into a table, a checklist ticked as tasks finish, a line added when an order comes in, the Now line of a live stream, the slides and the countdown of a show.
- Don't use it to store data for your own program: a note is for people to read. It holds rich text, checklists and tables, up to 5 MB.
- Don't use it to create notes. Notes start in the NoteSocket app (sync on), then the API writes to them.

## Getting access

- The API is part of Premium. Make a key in Account, API on notesocket.com (https://notesocket.com/account/api).
- Send the key in the Authorization header: `Authorization: Bearer nsk_...` (or `X-API-Key: nsk_...`). Never in the address: a key in the address is refused with 400 `key_in_address`.
- A note is named by its six-character code, the end of its link (notesocket.com/Hx7Qp2 is note `Hx7Qp2`).
- Base address: `https://api.notesocket.com/v1`. Every body is JSON. Times are UTC, ISO 8601.

## The calls

List the account's synced notes:

```
curl https://api.notesocket.com/v1/notes -H "Authorization: Bearer $NS_KEY"
```
```json
{"notes": [{"code": "Hx7Qp2", "title": "Quiz night scores", "rev": 214, "updated_at": "2026-09-30T13:52:04Z", "live": "live"}]}
```

Read a note (each tab's text, checklist items, tables, the live and the slides):

```
curl https://api.notesocket.com/v1/notes/Hx7Qp2 -H "Authorization: Bearer $NS_KEY"
```
```json
{"code": "Hx7Qp2", "title": "Quiz night scores", "rev": 214,
 "tabs": [{"name": "Scores", "text": "Quiz night, Friday\nRound 4...", "items": [{"n": 1, "text": "Hand out answer sheets", "done": true}], "tables": [{"n": 1, "rows": 5, "cols": 3}], "slides": 8}]}
```

Add a line at the end (or `"at": "top"`) of a tab:

```
curl -X POST https://api.notesocket.com/v1/notes/Hx7Qp2/lines -H "Authorization: Bearer $NS_KEY" -H "Content-Type: application/json" -d '{"text": "Round 5 starts at 21:15"}'
```
```json
{"note": "Hx7Qp2", "text": "Round 5 starts at 21:15", "at": "end", "rev": 215}
```

Tick (or untick) the n-th checklist item of a tab:

```
curl -X PATCH https://api.notesocket.com/v1/notes/Hx7Qp2/items/1 -H "Authorization: Bearer $NS_KEY" -H "Content-Type: application/json" -d '{"done": true}'
```
```json
{"item": 1, "text": "Collect round 3", "done": true, "was": false, "rev": 216}
```

Set one table cell, named like a spreadsheet (A1 is the top left; `"table": 2` for the second table):

```
curl -X PUT https://api.notesocket.com/v1/notes/Hx7Qp2/cells/B2 -H "Authorization: Bearer $NS_KEY" -H "Content-Type: application/json" -d '{"value": "42"}'
```
```json
{"table": 1, "cell": "B2", "value": "42", "was": "38", "rev": 217}
```

Every write can name a tab with `"tab": "Scores"`; without it, the first tab.

While the note is live:

- `PUT /v1/notes/{code}/now` with `{"text": "Round 5, music"}` changes the Now line on the live page and the stream overlay.
- `PUT /v1/notes/{code}/timer` with `{"action": "start", "secs": 300, "label": "Answers in"}` runs the countdown. Actions: `start`, `pause`, `resume`, `toggle`, `reset`.
- `POST /v1/notes/{code}/live` with `{"title": "Quiz night"}` goes live; `POST /v1/notes/{code}/live/end` ends it.

Slides and undo:

- `POST /v1/notes/{code}/slides/next` (or `prev`, or a number) moves the slide showing; the note page and a presenting app follow.
- `POST /v1/notes/{code}/undo` with `{"count": 1}` puts back the last changes a key made (ticks, cells, the Now line, slides, the timer), up to 3, within a day.

## Limits

- 60 calls a minute and 20,000 a day per key (the day is UTC). Over either: 429 `rate_limited`.
- A line up to 2,000 characters. A note up to 5 MB: past it, 413 `too_large`.
- An account holds up to 20 keys. A key that is switched off answers 401 `bad_key`.
- Only notes synced to the key's own account can be read or written.

## Errors

Every error is JSON with a status code:

```json
{"error": {"code": "not_found", "message": "There's no note Hx7Qp2 synced to this account."}}
```

- 400 `key_in_address`: the key was sent in the address, not the header.
- 401 `bad_key`: no key, an unknown key, or a key switched off.
- 402 `premium`: the account isn't on Premium; `upgrade_url` says where to get it.
- 404 `not_found`: no such note, tab, item, table or cell. The message names what there is.
- 409 `not_live`, `busy`, `not_running`, `not_paused`, `nothing_to_undo`, `changed`: the note isn't in a state for that. `busy`: try again in a moment.
- 413 `too_large`, 422 `bad_body` or `bad_ref`: the request itself; the message shows a correct example.
- 429 `rate_limited`: wait for the next minute (or the next UTC day).

## A typical workflow

1. `GET /v1/notes` to find the note's code by its title.
2. `GET /v1/notes/{code}` to see its tabs, items and tables, so the writes name the right item number, table and cell.
3. Write with `lines`, `items`, `cells`, `now` or `timer`. Each answer carries the note's new `rev`.
4. On 409 `busy`, wait a second and send it again. On 404, read the note again: someone may have changed it.
5. If a change was wrong, `POST /v1/notes/{code}/undo`.

Webhooks (Account, Webhooks) tell your own address when a note changes, an item is ticked or a live starts, signed with a secret: https://notesocket.com/documentation/webhooks.

## MCP server

The same calls as tools, for assistants that take a remote MCP server: `https://api.notesocket.com/mcp`, with the key in the header `Authorization: Bearer nsk_...`. Tools: list_notes, read_note, add_line, tick_item, set_cell, go_live, end_live, set_now, move_slides, countdown, undo. Each counts against the key's limits like a direct call. https://notesocket.com/documentation/mcp

## Documentation

- Every endpoint, with Try it: https://notesocket.com/documentation
- The whole manual in one markdown file: https://notesocket.com/documentation/manual.md
- OpenAPI: https://notesocket.com/openapi.json

Operator: DeveloperData.net.