NoteWay

Developers

Let AI apps and your own scripts work with Note Way. One key per app, only the rights you tick, and every change can be taken back.

Last updated: 4 November 2026

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

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.

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}$

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

For Ruby: bring your tasks along and keep them up to date

  1. 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.
  2. With Claude Code or Cursor (MCP): add the address https://api.noteway.ai/mcp with the header Authorization: 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.
  3. Or in the terminal (CLI): install the noteway command from the app (Settings → Control → Other AIs), then noteway login and tick the same rights in the browser. No key to copy.
  4. Move in: noteway import-tasks --source Todoist --file tasks.json first shows what would happen; if it fits, the same with --write. Back: noteway undo-import <import_id> --write.
  5. Every day: noteway capture "Dentist tomorrow at 9"; noteway complete <id>; noteway update <id> --time 10:30. Every answer names a change_id; noteway undo <change_id> takes it back, and so does Undo in Note Way.