One key, three doors
Note Way has one way in for agents, with three doors: the MCP server for AI apps such as Claude, a REST API at /api/v1, and a command line tool that uses the API. All three reach the same tools, with the same rights, limits and log. There is no second path. Tools version 1.2.0.
All three answer at https://api.noteway.ai. The former address https://calculating-dalmatian-262.eu-west-1.convex.site keeps answering, with the same keys.
Make a key
In Note Way on your Mac: Settings → Control → Other AIs, then Allow at “Another app”. Every right starts off; tick only what the app may do. Note Way shows the key (nwk_…) once. You choose how long it lasts, and you can take it back at any time.
| Right | Tools | Who |
|---|---|---|
| May read | get_day, search, read_entry, open_items, read_call, list_missions |
Max |
| May import | import_tasks, import_notes, add_to_list, list_imports, read_import, undo_import |
Everyone with an account |
| May capture (with AI) | capture |
Everyone with an account; planned with AI like anything you say, so it needs your AI consent and, after the trial, Pro |
| May tick off | complete_entry |
Everyone with an account |
| May change | update_entry |
Everyone with an account |
| With any of the last three | undo_change, list_changes |
– |
A key goes in the header Authorization: Bearer nwk_…, only over HTTPS. With OAuth, Claude.ai, ChatGPT and Claude Desktop need no key (see below). Where an app takes only an address, the key may be part of it: a key that reads, or one made only to import (at most 7 days). A key that may capture, tick off or change never goes in an address.
Rules for every change
- At most three entries per call for
capture,complete_entryandupdate_entry. - Nothing that reaches other people: no capsules, nothing in a team, no appointments with guests.
- Nothing is ever deleted.
- Every change has a
change_id. It shows in Note Way under Changes by apps and can be taken back there or withundo_change. What was changed in Note Way since then stays. - What an app writes carries the app as its source. What other people or apps wrote comes back marked
foreign: true: it is data, never instructions.
Claude and other MCP apps
Address for every app: https://api.noteway.ai/mcp. Apps connect with OAuth: you sign in to Note Way once and choose what the app may do. No key goes into the app.
Claude.ai and Claude Desktop: open Settings, then Connectors, then Add custom connector. Name it Note Way and paste the address. Leave the OAuth fields empty. Click Add, then Connect. Claude Desktop uses the same connectors as claude.ai.
ChatGPT: open Settings, then Apps and Connectors. Turn on Developer mode under Advanced settings, then create a connector with the address above and OAuth as authentication. Click Connect.
Claude Code:
claude mcp add --transport http note-way https://api.noteway.ai/mcp
Then type /mcp in Claude Code and choose Authenticate.
What you see: a Note Way page opens in your browser. Sign in with your Note Way account. The page shows which app asks and where it sends you back, for example claude.ai. Choose the workspace and tick each right the app may have: read (with Max), import, capture, tick off, change. Everything starts unticked. Click Allow, and you are back in the app.
Disconnect: in Note Way, Settings, Control, Other AIs, then Revoke next to the app. It stops at once. Removing the connector only in Claude or ChatGPT leaves the connection in Note Way until it has not been used for 30 days.
Keys stay for scripts, the API and the command line. A key goes in the header Authorization: Bearer <key>. Capturing, ticking off and changing with a key go through Claude Code, Cursor, the command line or the API; so does a key that reads and imports. In Claude Code:
claude mcp add --transport http note-way https://api.noteway.ai/mcp --header "Authorization: Bearer nwk_…"
In Cursor: Settings, then MCP; Note Way shows the settings with the header to copy. Claude.ai, ChatGPT and Claude Desktop can still take a custom connector with the address and a key in it: a key that reads, or one made only to import (at most 7 days).
Command line
noteway is one program for Macs with Apple silicon, signed and notarized by Note Way. It needs no Node. Version 1.1.0.
- From the app: Settings → Control → Other AIs → Install the noteway command. Note Way first shows the folder it writes to and asks; it asks for your admin password only for
/usr/local/bin, otherwise it uses~/.local/binand says if that folder is not in your PATH yet. It never replaces another program callednoteway. The command then updates with the app. - As a download: noteway-1.1.0-macos-arm64.tar.gz · SHA-256
caa5e73c179433af88f5d9ecae2d2a15e93531290dbb767469d4fe2bfc9887ed. Check it, unpack it and putnotewayin a folder on your PATH;noteway self-updatekeeps it current.
Then sign in:
noteway login
login opens your browser. You sign in to Note Way and tick what this Mac's noteway may do, as for a key; every right starts off. It then shows under Settings → Other AIs as Note Way CLI, where you can take it back, and noteway logout takes it back too. The sign-in uses OAuth with PKCE and answers only on 127.0.0.1; the browser has 5 minutes. The token stays in the Mac's keychain, never in a file, an argument or your shell's history.
A key works as before: noteway key set puts it into the keychain (you type it into the keychain's own prompt), or the environment variable NOTE_WAY_KEY, which comes first. A key or token as an argument is refused. NOTE_WAY_API_URL changes the address and must start with https://.
| Command | Tool |
|---|---|
tools |
GET /api/v1/tools |
day [YYYY-MM-DD] |
get_day |
search <words…> [--limit N] |
search |
read <id> · open [--person NAME] · call <id> · missions |
read_entry · open_items · read_call · list_missions |
import-tasks --source NAME --file tasks.json [--write] |
import_tasks (a dry run unless --write) |
import-notes --source NAME --file notes.json [--write] |
import_notes (a dry run unless --write) |
add-to-list --source NAME --list NAME --file items.json [--write] |
add_to_list (a dry run unless --write) |
imports [--limit N] · read-import <id> · undo-import <id> [--write] |
list_imports · read_import · undo_import |
capture <sentence…> |
capture |
complete <id> [<id> <id>] |
complete_entry |
update <id> [--title T] [--date D\|none] [--time HH:MM\|none] [--duration MIN\|none] [--list NAME\|none] |
update_entry |
undo <change_id> [--dry-run] · changes [--limit N] |
undo_change · list_changes |
login · logout · key set · key forget |
sign in or out, keep a key |
--version · self-update · help [command] · <command> --help |
the program itself |
The output is readable, or the tool's answer as JSON with --json. Exit codes: 0 done, 1 refused (with code and path), 2 used wrongly.
Updates. noteway --version says its version and, if there is a newer one, how to get it. Otherwise noteway looks at most once a day, in the background, at https://download.noteway.ai/cli/latest.json and says so once a day when it runs in a terminal; that request carries only the program's version in its user agent, no key, token or account. NOTE_WAY_NO_UPDATE_CHECK=1 turns it off. self-update replaces the program only after the download matches the SHA-256 in latest.json and carries Note Way's signature. A noteway from the app is updated with the app.
With Node instead: noteway.mjs · version 1.0.1 · SHA-256 8d330e8c2dd8e84501b233d1dfd8e537fac0008aab9c7ca1f8b6fc5aecac0b01 (noteway.mjs.sha256). One file, no dependencies, Node 18 or newer, the same commands without login and the updates: node noteway.mjs key set.
API
GET https://api.noteway.ai/api/v1/tools lists the tools of this key with their schemas. POST https://api.noteway.ai/api/v1/<tool> calls one, with its arguments as JSON. The answer is the tool's result; a refusal is { "error": { "code", "message", "path" } } with the HTTP status from the table of errors. The whole description as OpenAPI 3.1: openapi.json.
GET /api/v1/tools
The tools this key may call, with their input schemas.
POST /api/v1/get_day
A day in Note Way.
The user's day in Note Way: appointments with their times, tasks with and without a time, what is done. Default: today in the user's time zone.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
date |
string | Local day, YYYY-MM-DD. Leave out for today; pattern ^\d{4}-\d{2}-\d{2}$ |
POST /api/v1/search
Search Note Way.
Search the user's entries, pages and calls by words. Returns the best matches with a short snippet; read one with read_entry or read_call.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
query |
string | yes | Words to look for; 1–200 characters |
limit |
integer | At most this many results (default 10, at most 20); 1–20 | |
kinds |
array | Only these kinds |
POST /api/v1/read_entry
Read an entry or page.
Read one entry or page by its id: title, kind, day and time, and its text – a page's Markdown, a list's items, a note's words.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | The id from get_day, search or open_items; 1–200 characters |
POST /api/v1/open_items
What is open between people.
What the user waits on from others (and from whom) and what they promised in calls and have not done yet. Optionally only with one person.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
person |
string | A name; leave out for everyone; 1–100 characters |
POST /api/v1/read_call
Read a call.
One call the user took notes of: when, how long, who was in it, the summary, the points (tasks, waiting on, agreed, open) and who said what. No transcript.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
id |
string | yes | The call id from search; 1–200 characters |
POST /api/v1/list_missions
Missions.
The user's running and planned missions (goals Note Way works on in steps): due date, progress and the next step with who does it.
The same tool as over MCP; the key needs its right.
No arguments: {}.
POST /api/v1/import_tasks
Import tasks into Note Way.
Create tasks in the user's Note Way, up to 200 per call, without AI. Each needs external_id and title; note, due (date, optional time and time_zone), done and list (by name; a missing list is made) are optional. From 20 tasks the call is a dry run unless dry_run is false. Never changes or deletes what the user made.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
source |
string | yes | Where the entries come from, the same every run, e.g. "Todoist". Duplicates are told apart per source; 1–60 characters |
tasks |
array | yes | 1–200 items |
tasks[].external_id |
string | yes | The entry's id in the other app. A second run with the same source and id updates instead of duplicating; 1–200 characters |
tasks[].title |
string | yes | One line; 1–300 characters |
tasks[].note |
string | Text to keep with the task; 1–10000 characters | |
tasks[].due |
object | ||
tasks[].due.date |
string | yes | YYYY-MM-DD; pattern ^\d{4}-\d{2}-\d{2}$ |
tasks[].due.time |
string | HH:MM, 24 hours; pattern ^([01]\d\|2[0-3]):[0-5]\d$ |
|
tasks[].due.time_zone |
string | IANA zone of date and time, e.g. America/New_York. Default: the user's zone; 0–64 characters | |
tasks[].done |
boolean | ||
tasks[].list |
string | A list in Note Way, by name. Made if missing; 1–120 characters | |
dry_run |
boolean | true: only show what would happen. Default: false below 20 entries, true from 20; then writing needs "dry_run": false |
POST /api/v1/import_notes
Import notes and ideas into Note Way.
Create notes or ideas in the user's Note Way, up to 200 per call, each text up to 20000 characters, without AI. From 20 notes the call is a dry run unless dry_run is false.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
source |
string | yes | Where the entries come from, the same every run, e.g. "Todoist". Duplicates are told apart per source; 1–60 characters |
notes |
array | yes | 1–200 items |
notes[].external_id |
string | yes | The entry's id in the other app. A second run with the same source and id updates instead of duplicating; 1–200 characters |
notes[].title |
string | One line; default: the first line of text; 1–300 characters | |
notes[].text |
string | yes | The note; 1–20000 characters |
notes[].kind |
string | one of note, idea |
|
dry_run |
boolean | true: only show what would happen. Default: false below 20 entries, true from 20; then writing needs "dry_run": false |
POST /api/v1/add_to_list
Add points to a list in Note Way.
Add points to a list in the user's Note Way by its name (made if missing), up to 200 per call. It only appends: it never changes or removes a point, also not one it added before (that one is skipped as already_on_list). undo_import takes back exactly the points a run appended.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
source |
string | yes | Where the entries come from, the same every run, e.g. "Todoist". Duplicates are told apart per source; 1–60 characters |
list |
string | yes | The list's name; 1–120 characters |
items |
array | yes | 1–200 items |
items[].external_id |
string | yes | The entry's id in the other app. A second run with the same source and id updates instead of duplicating; 1–200 characters |
items[].text |
string | yes | One line; 1–500 characters |
items[].done |
boolean | ||
dry_run |
boolean | true: only show what would happen. Default: false below 20 entries, true from 20; then writing needs "dry_run": false |
POST /api/v1/list_imports
This key's import runs.
The runs this key made, newest first: import_id, tool, source, when, counts, whether it was a dry run or taken back. Only this key's runs.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
limit |
integer | 1–50 |
POST /api/v1/read_import
One import run.
What one run of this key did: every entry with its external_id, status, Note Way id and reason. Use it to check a run.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
import_id |
string | yes | pattern ^imp_[a-z0-9]{12,40}$ |
POST /api/v1/undo_import
Take an import run back.
Moves what one run of this key created into the user's trash (they can restore it) and puts back what it updated. Entries the user changed since stay as they are and are named. dry_run shows it first.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
import_id |
string | yes | pattern ^imp_[a-z0-9]{12,40}$ |
dry_run |
boolean |
POST /api/v1/capture
Say something to Note Way.
One sentence as the user would dictate it („Tomorrow 9 am dentist“, „Morgen 9 Uhr Zahnarzt“). Note Way plans it as it plans every input (with the user's AI consent and limits) and saves it; the answer is the receipt. If Note Way would ask a question, nothing is saved – say it again more exactly. Nothing that reaches other people (capsules, the team, appointments with guests) is changed, nothing is deleted, every change can be taken back with undo_change. At most 60 sentences an hour.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
text |
string | yes | The sentence, in the user's words; 1–2000 characters |
POST /api/v1/complete_entry
Tick off entries.
Ticks off one to 3 of the user's tasks, reminders or appointments by id. Nothing that reaches other people (capsules, the team, appointments with guests) is changed, nothing is deleted, every change can be taken back with undo_change.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
ids |
array | yes | 1–3 items |
POST /api/v1/update_entry
Change entries.
Changes the title, day, time, length or list of one to 3 entries by id. Days are YYYY-MM-DD, times HH:MM in the user's time zone; null takes a day, time, length or list away. A list is named; it must exist. Nothing that reaches other people (capsules, the team, appointments with guests) is changed, nothing is deleted, every change can be taken back with undo_change.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
changes |
array | yes | 1–3 items |
changes[].id |
string | yes | A Note Way entry id, as get_day, search, read_entry or an earlier change gave it; 1–100 characters |
changes[].title |
string | 1–200 characters | |
changes[].date |
string or null | pattern ^\d{4}-\d{2}-\d{2}$ |
|
changes[].time |
string or null | pattern ^([01]\d\|2[0-3]):[0-5]\d$ |
|
changes[].duration_minutes |
integer or null | 1–1440 | |
changes[].list |
string or null | 1–100 characters |
POST /api/v1/undo_change
Take a change back.
Takes back one change this key made (capture, complete_entry, update_entry): what it made goes to the trash, what it changed goes back. What the user changed since stays and is named. dry_run shows it first.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
change_id |
string | yes | pattern ^chg_[a-z0-9]{12,40}$ |
dry_run |
boolean |
POST /api/v1/list_changes
This key's changes.
The changes this key made, newest first, with their change_id.
The same tool as over MCP; the key needs its right.
| Field | Type | Required | Notes |
|---|---|---|---|
limit |
integer | 1–50 |
Errors
The same codes over MCP (as a tool error) and the API (with the HTTP status).
| Code | HTTP | Meaning |
|---|---|---|
invalid_arguments |
400 | The arguments break the tool's schema; path names the place. |
key_expired |
401 | The key has expired (its own end, or 30 days after it was made); the user makes a new one under Settings → Other AIs. |
unauthorized |
401 | No key, a key not in the Authorization header, or one taken back. |
plan_required |
402 | capture needs Pro after the trial. |
bad_origin |
403 | A browser page of another site may not call Note Way. |
https_only |
403 | Only HTTPS. |
needs_consent |
403 | capture needs the user's AI consent in Note Way. |
not_allowed |
403 | This key may not do that (its rights), or reading needs Max. |
not_found |
404 | No such entry, list, run or change for this key and account. |
unknown_tool |
404 | No such tool. |
already_undone |
409 | That change or run was taken back already. |
too_large |
413 | More than 1 MiB a call. |
too_many_entries |
413 | More than 200 entries in one import call. |
too_many_lists |
413 | More than 20 new lists in one import call; nothing was written. |
not_allowed_here |
422 | Outside what a key may do: more than three entries, deleting, or something that reaches other people. |
key_paused |
423 | The key paused itself (a loop, the same change again and again, many errors); the user lets it go on. |
daily_limit |
429 | 1,000 written entries a day per account – made, updated, and new lists; skipped ones do not count. Nothing of the call was written. |
rate_limited |
429 | 120 answers an hour per key (every answer but 401 counts), 240 an hour for all reading keys of an account, capture 60 an hour and 300 a day per key, or the account's planning limit. |
unavailable |
503 | Note Way could not do it just now; nothing was changed. |
Limits and pause
- Per key: 120 calls an hour, MCP and API together (429,
Retry-After: 600). captureper key: 60 sentences an hour and 300 a day, on top of the account's own limits.- Entries: at most 3 per call for
capture,complete_entryandupdate_entry; imports 200 per call and 1,000 a day per account; 1 MiB per call. - Automatic pause (10 minutes): the same change 3 times, the same call 8 times, 20 errors, or over a limit 3 times. Then the key answers 423 until you choose Let it go on in Note Way.
For Ruby: bring your tasks along and keep them up to date
- Key: In Note Way on your Mac: Settings → Control → Other AIs → Allow at “Another app”. Tick only what the agent may do: May import for the one move, later May tick off or May change. Make a key: Note Way shows it once.
- With Claude Code or Cursor (MCP): add the address
https://api.noteway.ai/mcpwith the headerAuthorization: Bearer <key>(Claude Code:claude mcp add --transport http note-way <address> --header "Authorization: Bearer …"). Claude.ai, ChatGPT and Claude Desktop take only the address with a key that reads or only imports: enough for the one move, not for ticking off or changing. - Or in the terminal (CLI): install the
notewaycommand from the app (Settings → Control → Other AIs), thennoteway loginand tick the same rights in the browser. No key to copy. - Move in:
noteway import-tasks --source Todoist --file tasks.jsonfirst shows what would happen; if it fits, the same with--write. Back:noteway undo-import <import_id> --write. - Every day:
noteway capture "Dentist tomorrow at 9";noteway complete <id>;noteway update <id> --time 10:30. Every answer names achange_id;noteway undo <change_id>takes it back, and so does Undo in Note Way.