Skip to content

REST API ​

A small, deliberately narrow API for reading and editing maps from your own code. A task is a node with an assignee or a deadline — there is no separate task object. It is the same surface the MCP server is built on.

Looking for a worked example?

Connecting Google Sheets is the whole recipe step by step — code for Apps Script and for n8n, conflict handling (409) included.

  • Works for the cloud and the free self-hosted instance alike — a hosted instance (yourcompany.killbottleneck.com) exposes the same API as one on your server; only the address differs
  • Base path: /api/kb/v1 — the older /api/flowmap/v1 prefix still resolves to the same handlers
  • Authentication: an API key in the Authorization header. Never a session cookie or JWT
  • Format: JSON in, JSON out
  • Language: English only, by design

Authentication ​

Create a key in the application: menu by your name → API keys — a description, Permissions (Read only / Read and write), an optional Valid until, Create. The plaintext token is shown once — only its SHA-256 hash is stored, so a lost key cannot be recovered, only rotated (Rotate key issues a new token, the old one stops working). The same list also shows tokens created by approving an AI agent through OAuth (Connect AI agent; valid for 90 days) — they are revoked the same way.

API keys — a new key is shown only once. The block on top shows the instance address and a ready-made MCP command.
Authorization: Bearer kb_user_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys issued before the rename start with fm_user_ and keep working.

Only /api/kb/v1/* is the public API

The app itself talks to many other /api/kb/* routes (/my-day, /portfolio, /export, /import-all, /share, /chat/faktury, …). Those are internal, authenticated by the browser session, and an API key gets 401 on them. They are described as features, not as endpoints, and may change between versions without notice (invoices from the assistant have no public API). The second public entry point is /mcp — same authentication, same limits.

Scopes ​

ScopeMay call
readevery GET endpoint
read_writeeverything, including all POST endpoints

A read key calling a write endpoint gets 403. The default when creating a key is read.

What a key can never do ​

  • The owner comes from the key, never from the request body. A key acts as its owner: it reaches exactly the maps the owner can see in the app — own maps, team maps and maps shared with the owner — and writes according to the share level (owner/edit = full write; work and read = only the status of the owner's own nodes via POST …/nodes/{nodeId}, exactly like ticking off in the app; anything else → 403). GET /v1/maps and GET /v1/maps/{id} return the level as access.
  • A key cannot escalate over maps. The server never establishes a session for it and does not read the account's role for maps, so an API key cannot do administrator things — an admin's key sees no private map of anyone else, and a read-scope key never writes whatever the share level. The exception since v0.83: for shared calendars the role is read — an admin's or manager's key creates, changes and deletes calendars with their events and decides time off, exactly like its owner in the app.
  • A map the owner cannot see returns 404, not 403 — the API does not confirm that an id exists. Someone else's public map is 404 too: a public board is not working access.
  • Assigning an owner through the API shares the map with that person as a collaborator (work), exactly like the app does (never downgrades, never for external contacts) — but only when the key owner may share at all (map owner or a named editor; a team editor assigns without sharing, as in the app). The response lists who was shared with in shared.
  • Rules and their run log (GET …/rules, …/rule-runs) are visible only with edit rights, as in the app; readers and collaborators get 403.

Limits ​

LimitValue
Requests per minute, read120 per key
Requests per minute, read_write30 per key
Request body2 MB
Items per call (nodes)200
Keys per account20
GET /v1/portfolio60 per minute per user, on top of the per-key limit
Rules per map / rule templates per author50 / 50
Events per user / shared calendars per instance2,000 / 100
Participants per event / members per calendar50 / 200
Events in one GET /v1/events listing3,000 (then truncated: true)

Read and write are counted in separate buckets, so bulk reading cannot starve your writes. Over the limit you get 429.

Optimistic locking ​

Every endpoint that changes an existing map requires base_updated — the updated value you got when you last read the map.

GET  /api/kb/v1/maps/{id}        →  { "updated": "2026-07-30 08:12:44.031Z", … }
POST /api/kb/v1/maps/{id}/nodes  ←  { "base_updated": "2026-07-30 08:12:44.031Z", … }

Omit it and you get 400. Send a stale one and you get 409 — someone changed the map in the meantime. Re-read the map, re-apply your change, try again.

This is deliberate: it makes "write without reading first" impossible, which is exactly the mistake an over-eager AI assistant makes.

Endpoints ​

GET /api/kb/v1/maps ​

Lists the maps the key owner can see — own, team and shared with the owner. Every item carries access: owner, edit, work or read, and project_number — the project's number (#12), one sequence per instance, assigned by the server and never changed (0 = no number, e.g. the organization map), and kind: project (something to finish, % done), process (keeps running: recurring steps, run health instead of %) or org (the organization structure).

QueryMeaning
archived=1list archived maps instead of active ones
json
{
  "maps": [
    { "id": "abc123", "title": "Website relaunch", "project_number": 12, "node_count": 14, "updated": "2026-07-30 08:12:44.031Z", "access": "owner" }
  ]
}

GET /api/kb/v1/maps/{id} ​

One map as a tree. No canvas positions — the shape, not the drawing. Carries kind (as in the list); a process also carries health: recurring, late, ok, runs30, last and steps[] (each recurring step with its rhythm — freq, every, days, day, reset — deadline, late, last_at, runs30/90, late90).

json
{
  "id": "abc123",
  "title": "Website relaunch",
  "project_number": 12,
  "description": "",
  "archived": false,
  "updated": "2026-07-30 08:12:44.031Z",
  "access": "owner",
  "tree": [ {
    "id": "n_1", "type": "goal", "title": "Content", "status": "todo", "description": "",
    "deadline": "2026-08-15", "planned_on": "", "owner": "anna@example.com", "color": "", "icon": "✍️",
    "wait_for_children": false, "executor_kind": "human", "executor_name": "",
    "automation_wanted": false, "automation_note": "", "children": []
  } ],
  "notes": []
}

Keep the updated value — you need it as base_updated for any write.

The first call live: GET /v1/maps with the key in the header. Save the updated value — without it you cannot write anything.

Node fields ​

One shape everywhere: what GET …/maps/{id} returns per node is what tree/items accept when creating and what POST …/nodes/{nodeId} accepts when updating. Any other field is a 400 that lists the allowed ones (and, for common names from other tools, the killBottleneck equivalent).

FieldTypeMeaning
id, typeread-onlytype is apex (the root goal) or goal
titlestring, ≤ 200required when creating
statustodo / in_progress / donedefault todo; done may unblock waiting nodes and fire rules
descriptionstringfree text
deadlineYYYY-MM-DD or ""an agreement with someone else — nothing in the app moves it silently; "" clears
planned_onYYYY-MM-DD or ""the plan: when the key owner intends to work on it, today to 7 days ahead; "" clears. This is how killBottleneck expresses priority — there is no priority field
ownere-mailthe accountable person: an instance member or an external contact the key owner can see (GET …/members); unknown → 400 with a hint
color#rrggbb or ""node colour
iconan emoji or ""the icon shown in front of the step (the assistant sets one automatically); a string of up to 16 characters, longer ones are trimmed by the server without an error
wait_for_childrenbooleanthe node waits until its whole subtree is done
executor_kindhuman / automationwho performs the step (the owner stays a human either way)
executor_namestring, ≤ 100which automation handles it — a record, not an instruction
automation_wantedbooleana wish that this step were automated; notifies the AI agent managers
automation_notestring, ≤ 1000context for the wish
childrenarraytree items only (tree / items), nested recursively; their order is the order on the canvas (left to right) — what Sort in the editor changes

POST /api/kb/v1/maps ​

Creates a map from an outline. Requires read_write.

FieldRequiredMeaning
titleyesMap title, trimmed to 200 characters
treenoArray of items (see below); max 200 nodes in total
descriptionnoFree text
apex_textnoText of the root goal; defaults to title
kindnoproject (default) or process; anything else → 400. The style can be switched later in the app (owner only)

Each item in tree may carry title, description, deadline, planned_on, owner, status, color, icon, wait_for_children, executor_kind, executor_name, automation_wanted, automation_note and children. Layout is computed for you.

Returns { id, title, updated, tree }.

Unknown fields are rejected, not ignored

Every write endpoint answers 400 to a field it does not know — top-level or inside an item — and the message lists the allowed fields. Common names from other tools get a hint: priority → planned_on, due_date → deadline, assignee → owner, tags → structure or color, reminder / remind_at / time / hour → the reminders endpoint (a node has no time of day; a deadline_approaching rule remains the way to get an untimed alert or one for a whole map), event / meeting → the events endpoint; on events room / location / vacation / absence → calendar and end / until / duration → end_day / end_time. A typo therefore fails loudly instead of returning 200 and changing nothing.

POST /api/kb/v1/maps/{id} ​

Renames a map or changes its description — the project as a whole (the map list and the database show this title), not the apex node. Requires read_write and full write access to the map (owner, named edit share or team edit); the org structure is read-only through a key (403).

FieldRequiredMeaning
titlenoNew title, trimmed to 200 characters; empty → 400
descriptionnoNew description, up to 4000 characters; empty string clears
base_updatedyesThe updated you last read; a different value → 409

At least one of title / description must be present (400 otherwise). Returns { id, updated, title, description }.

POST /api/kb/v1/maps/{id}/nodes ​

Adds a subtree. Requires read_write.

FieldRequiredMeaning
base_updatedyesVersion you read (see optimistic locking)
itemsyesArray of items, at least one, max 200
parent_idnoWhere to attach; omitted = under the apex

Returns { updated, added_ids, tree }.

This re-computes the layout of the whole map

Adding nodes rearranges positions across the map. It is not a surgical insert.

POST /api/kb/v1/maps/{id}/nodes/{nodeId} ​

Updates one node. Requires read_write and base_updated.

Settable fields: title, status (todo / in_progress / done), description, deadline (YYYY-MM-DD, empty string clears), planned_on (see below), owner (e-mail, empty string clears), wait_for_children, color, icon, executor_kind, executor_name, automation_wanted, automation_note. Anything else is a 400 with the list of allowed fields. The node in the reply does not carry icon — read it back through GET …/maps/{id}.

planned_on is the plan, not the deadline. It says when the key owner intends to work on the node — today to 7 days ahead (YYYY-MM-DD, empty string clears the plan; a date outside that window is a 400). This is how killBottleneck expresses priority: there is no priority field on purpose, and the deadline is an agreement with someone else that must never be moved to say "this is important". A node planned for today shows up in My day exactly as if the person had planned it in the app. Every read (GET …/maps/{id}, the tree in write responses) returns planned_on as well.

Returns { updated, shared, node } — the new map version, who got the map shared because of a new owner, and the stored node (id, title, status, deadline, planned_on, owner, executor_kind, executor_name, automation_wanted). Read the value back from there: what the response shows is what the map holds.

Setting status to done has side effects on purpose: it may unblock waiting nodes, notify their owners, and trigger automations attached to them.

POST /api/kb/v1/maps/{id}/nodes/{nodeId}/delete ​

Deletes a node including its whole subtree. Requires read_write and base_updated.

The apex cannot be deleted, and whole maps cannot be deleted through the API at all. There is no undo — read the map and check the id first.

GET /api/kb/v1/maps/{id}/rules ​

Automation rules of the map (“when X → do Y”) — id, name, enabled, trigger, conditions, actions, last_fired (last time-based run — schedule/deadline_approaching; empty for event rules) and last_error (a non-empty error means the rule is broken and the map owner has been notified).

POST /api/kb/v1/maps/{id}/rules ​

Creates a rule. Requires read_write. Limits are structural only: 50 rules per map, 10 actions and 20 conditions per rule — runs are never counted or billed. A rule applies to future events only, never retroactively.

FieldRequiredMeaning
nameyesrule name (max 120 chars)
triggeryes{"type": …} — node_status_changed (optional status), node_unblocked, deadline_approaching (when: before/overdue, days 0–365), node_created, file_uploaded, schedule (freq: daily/weekly, weekday 1–7, hour 0–23)
actionsyesarray of 1–10 actions, executed in order: set_status, set_owner (member e-mail or the dynamic target deputy_of_node_owner), set_deadline (date, relative_days, or advance = daily/weekly/monthly — advances the node's current deadline by one interval, keeping the rhythm anchored to the original deadline: every Monday stays a Monday, the 31st stays the 31st clamped in shorter months; past occurrences skip to the nearest future one; with advance optionally every = every N-th day/week/month 1–4, days = weekdays 1–7 (1 = Monday, weekly only) and month_day = day of the month 1–31 (monthly only; the 31st in a shorter month = its last day, the next month the 31st again); "today" is the instance's day in its TZ) — these three accept target: trigger_node (default) / parent / a node id, move_node (to = id of the new parent; moves the TRIGGER node and appends it at the end of its new row — the kanban move; the apex, a vanished target or a cycle = an acknowledged skip in the log), create_subnodes (items = same tree as add_nodes, max 50 nodes), notify (to: node_owner/deputy_of_node_owner/map_owner/e-mail, message), reset_subtree (no parameters, trigger node only: its sub-goals and tasks back to To do — a recurring step's checklist starts over; a recurrence rule in a process carries it, switching the map style adds or removes it), offer_assistant (mode: rozbor/po_schuzce/priprava/revize/trideni/porada/nocni, to as in notify; only a notification with a link into the assistant, nothing runs without a click), run_agent (agent_name from the registry)
conditionsnoAND chain of {field, op, value} — field: status/owner/deadline/executor_kind/parent (id of the parent node — "card under a column", eq/ne only); op: eq/ne/empty/not_empty/before/after (deadline only, YYYY-MM-DD)
node_idnoscope the rule to one node; required for schedule rules with node-targeted actions
enablednodefaults to true

Defaults when a field is omitted: deadline_approaching has when: before and days: 1, schedule has hour = KB_AUTO_HOUR (default 5); relative_days in set_deadline is 0–3650 and message in notify is at most 500 characters.

Scheduled triggers run within the hour after the configured hour (server local time) — no “exactly at midnight” promise; after an outage they catch up the same day. deadline_approaching with when=overdue fires when the deadline is at least days past — it also catches deadlines that expired before the rule existed — and fires once per deadline (a changed deadline may fire again); when=before fires on the exact day (deadline − days). Rule chaining (an action firing another rule) is allowed up to depth 3, then the run ends with an explicit skipped log entry.

Dynamic targets resolve when the rule runs, not when the rule is saved — staff changes never break a rule. deputy_of_node_owner = the deputy of the trigger node's responsible person: org-structure position deputies take precedence (several positions with different deputies → notify goes to all of them, set_owner is skipped with advice to target a specific position), the personal deputy from Organization settings is the fallback. position:<nodeId> / deputy_of_position:<nodeId> target the holder/deputy of an org-structure position (GET /v1/org-structure lists the ids). An unresolvable target (no deputy, vacant or deleted position) skips the action and the run log says so — the rule is not marked as broken. Targets derived from the trigger node need node_id on a map-level schedule rule; position: targets do not.

POST /api/kb/v1/maps/{id}/rules/{ruleId} ​

Updates a rule. Passing only {"enabled": true/false} toggles it; otherwise send the full new shape (partial field edits are not merged). Editing clears the rule's error state.

POST /api/kb/v1/maps/{id}/rules/{ruleId}/delete ​

Deletes a rule. Its run log stays (with a name snapshot).

GET /api/kb/v1/maps/{id}/rule-runs ​

Run log of the map's rules (newest first, max 100). ?rule= limits to one rule. status: ok / failed / skipped (loop safety stop or per-save cap — detail says which).

GET /api/kb/v1/rule-templates ​

Instance-wide library of rule templates (rule shape without a map or node scope). To “load” a template, send its trigger/conditions/actions to POST …/rules of the target map — an independent copy is created.

POST /api/kb/v1/rule-templates ​

Creates (or with id updates — author or admin only) a template: name (unique), trigger, actions, optional conditions. A template must not carry node_id and create_subnodes may only target trigger_node. Requires read_write. Cap: 50 templates per author (400 You have the maximum number of templates).

POST /api/kb/v1/rule-templates/{id}/delete ​

Deletes a template (author or admin only). Rules already loaded from it stay in their maps.

GET /api/kb/v1/portfolio ​

Limit: 60 per minute per user (on top of the per-key limit).

The view from above — the same JSON as the Organization page (counts, scope, sections.projects / overdue / stuck / bottlenecks / people / changes, truncated; counts carries bottlenecks too), computed over the team and shared maps the key owner can read; the owner's private maps are excluded even from totals. Each item in sections.projects carries kind; a process has pct, done and total set to null (it is never "finished") and carries health instead (see the map detail). counts.projects counts all maps, processes included; counts.processes how many of them are processes. Optional ?today=YYYY-MM-DD. The role is not read: a plain member gets the summary of their own maps (in the app the page itself is admin/manager only). MCP: get_portfolio.

GET /api/kb/v1/members ​

Who you can assign work to: the instance members and the external contacts the key owner can see. Response: {members: [{id, email, full_name, name, role}], external_contacts: [{id, name, owner_email}]} — a safe subset, never notification settings or secrets. Use email (or an external contact's pseudo-address ext-<id>@kontakt.invalid from owner_email) as the owner of a node; an unknown e-mail is rejected with 400 and a hint of who you probably meant. MCP: list_people.

GET /api/kb/v1/org-structure ​

The organization structure (the org map): positions and functions with node ids, holders and deputies. Response: {exists, map_id, positions: [{node_id, title, position_kind, holder, deputy}]} where position_kind is position (defined by the structure) or function (appointed). Use node_id as the dynamic rule target position:<nodeId> (holder) or deputy_of_position:<nodeId> (deputy of that position) — both resolve when the rule runs, so staff changes never break a rule. An archived org map counts as "no structure" everywhere (exists: false, position targets skip). Read-only: holders and deputies are appointed by an admin in the app (Organization settings) — the API-key contract never reads user roles, so there is no write endpoint here.

Events ​

An event is a calendar item with a time — a meeting, a call, the dentist. It is not a task: it belongs to no map, has no status or assignee, and changes nothing in any project. In the app it lives in the calendar (/kalendar) — personal under the Events row, or in a shared calendar (company events, room/resource, time off; see calendars). Times are the instance's local time (TZ), as YYYY-MM-DD plus HH:MM strings — never ISO timestamps with an offset.

The key owner sees their own events, those they were invited to, and the events of the shared calendars they can see (not a selected people only calendar they are not a member of, and not an archived one; a rejected time off only the requester, the person concerned and an admin); edits their own, in a shared calendar also others' as admin/manager, and their own time off. MCP: create_event, create_events, update_event, delete_event, list_events, list_calendars, create_calendar, who_is_away.

Event object (returned everywhere):

json
{
  "id": "ev1", "title": "Dentist", "day": "2026-09-20", "time": "14:00", "note": "", "place": "12 Main St", "series": "",
  "owner_email": "me@example.com", "participants": ["anna@example.com"],
  "remind": true, "remind_before_min": 30, "mine": true, "can_edit": true,
  "end_day": "", "end_time": "15:00", "calendar": "", "calendar_name": "", "kind": "",
  "created": "2026-09-19 10:01:12.004Z", "updated": "2026-09-19 10:01:12.004Z"
}

time is "" for an all-day event; end_time is the end on the same day, end_day the last day of a multi-day event; participants are member e-mails; mine says whether the key owner created it, can_edit whether they may change it; calendar / calendar_name / kind (shared | resource | absence) are empty for a personal event. Time off also carries away (e-mails of who is away), status ("" without approval, requested / approved / rejected) and decision_note.

GET /api/kb/v1/events ​

Events in a day window — own, invited and from the shared calendars the key can see, ordered by day and time.

QueryMeaning
from, toYYYY-MM-DD, inclusive; default today − 365 … today + 730. A multi-day event counts when it overlaps the window
calendarname or id of a shared calendar — only its events

Returns { events: [...], from, to, truncated } — at most 3,000 events; with truncated: true narrow the window. An unknown calendar returns an empty list, not a 404.

POST /api/kb/v1/events ​

Creates an event. Requires read_write.

FieldRequiredMeaning
titleyes≤ 200 characters
dayyesYYYY-MM-DD
timenoHH:MM (24 h); omit or "" = all day
noteno≤ 2000 characters
placenowhere it takes place, ≤ 200 characters (a room, an address). A room to book is a shared calendar (calendar)
participantsnoarray of member e-mails (max 50). Instance members only — an unknown address or an external contact is a 400 with a hint (GET …/members). Each invitee gets an event invited notification and sees the event in their calendar
remindnoboolean; a reminder for the owner and all invitees
remind_before_minno0–10080 minutes before the start (0 = at the start); sending it implies remind: true, remind: true without it means 30. All-day event: the reminder arrives in the morning at KB_DEADLINE_HOUR
end_timenoHH:MM, end on the same day; only with time
end_daynoYYYY-MM-DD, last day of a multi-day event (vacation); ≥ day
calendarnoname or id of a shared calendar; omitted or "" = personal. A room/resource requires time (without end_time one hour is booked) and an overlap is 409 { error, collision, next_free } — next_free is the first free {day, time, end_time} that day, or null. Time off should be entered as all-day (omit time; the server does not enforce it); participants = who is away (empty = the key owner; entering it for a colleague is admin/manager only, otherwise 403); in a calendar with approval it is created with status: "requested". Room: the next_free replacement is searched the same day up to 20:00 only

Returns { event }. No base_updated — events are not part of a map.

POST /api/kb/v1/events/batch ​

Creates several events at once — the dates of an invitation, a lecture schedule, trainings. Requires read_write. { items: [{ title, day, time?, end_day?, end_time?, note?, place? }], calendar?, participants?, remind_before_min? } — items 1–30, the shared fields apply to all. All or nothing: an invalid item is 400 naming the item number and nothing is written. An event the key owner already sees with the same title (ignoring case and diacritics), day and time is skipped. Time off (absence) cannot be batched. Invitees get one notification for the whole batch.

Returns { events: [...], skipped: [{ title, day, time, existing_id }], series } — series is the shared id of the created events ("" for a single event).

POST /api/kb/v1/events/series/{series}/delete ​

Deletes every event of the series the key owner may change. Returns { success, events_deleted }, otherwise 404.

POST /api/kb/v1/events/{id} ​

Updates an event; send only the fields to change (same fields as when creating). The owner; in a shared calendar also an admin/manager; time off also the person it concerns. Otherwise 403, an event the key owner cannot see is 404. Moving day of a multi-day event without end_day keeps its length. Changing the day, time or reminder re-arms the reminder; new invitees are notified, existing ones are not notified again. Changing the dates or people of an already decided time off puts it back to requested.

POST /api/kb/v1/events/{id}/delete ​

Deletes an event. Whoever may edit it: the owner, in a shared calendar also an admin/manager, for time off also the person it concerns (403 / 404 as above).

POST /api/kb/v1/events/{id}/leave ​

Removes the key owner from the participants of an event they were invited to (the event disappears from their calendar). The creator cannot leave (400) — they delete instead; someone who sees the event (shared calendar) but is not invited → 400 You are not invited to this event; an invisible event → 404.

POST /api/kb/v1/events/{id}/decide ​

Decides on time off in a calendar with approval switched on — admin or manager only (otherwise 403). Body { decision: "approved" | "rejected", note? } (note ≤ 500 characters, shown to the requester). The decision can be changed; the requester and the person concerned are notified. Time off without approval → 400.

Shared calendars ​

A calendar that is not a person: company events (shared), room / resource (resource — bookings never overlap) and time off (absence). With visibility: all every member sees them, with members only the selected people (see below); every member adds events, or admins and managers only (write_access: "admins"). Created and changed by an admin or manager only — through an API key too; they are archived, or deleted together with their events. MCP: list_calendars, create_calendar, delete_calendar.

Calendar object: { id, name, kind, color, description, visibility, members, write_access, needs_approval, archived, can_write, can_manage, events_count, created, updated }. visibility is all (whole team) or members (only members — member e-mails — plus the creator; to everyone else, admins included, the calendar and its events are invisible, 404).

GET /api/kb/v1/calendars ​

The calendars the key owner can see, including archived ones, by name (a selected people only calendar they are not a member of is not listed).

POST /api/kb/v1/calendars ​

Creates a calendar (read_write, admin/manager). Fields: name (required, ≤ 80, unique regardless of case), kind (required), color (#RRGGBB), description (≤ 500), write_access (all | admins), needs_approval (time off only), visibility (all | members), members (member e-mails, max 200). Returns { calendar }. Cap: 100 calendars per instance (400).

POST /api/kb/v1/calendars/{id} ​

Updates a calendar (same fields + archived); kind cannot change after creation (400).

POST /api/kb/v1/calendars/{id}/delete ​

Deletes the calendar together with all its events ({ success, events_deleted }) — admin/manager, cannot be undone; archive when the history should stay.

GET /api/kb/v1/away ​

Who is away: time off that is approved or needs no approval in the window from–to (default today … +14), one row per person and event: { away: [{ email, from, to, title, calendar, event_id }], from, to }. MCP: who_is_away.

Reminders ​

A timed reminder on a node, relative to its deadline: offset_days before the deadline (0 = on the deadline day, 1 = the day before …) at time. It is private to the key owner (the node stays as it is for everyone else), there is one per person and node, and it never changes the deadline — when the deadline moves, the reminder moves with it. A node that is done, deleted or loses its deadline drops the reminder. The map only has to be visible to the key owner; no base_updated, because nothing in the map changes. MCP: create_reminder.

GET /api/kb/v1/maps/{id}/nodes/{nodeId}/reminders ​

The key owner's reminder on the node — { reminders: [...] }, empty or one item.

POST /api/kb/v1/maps/{id}/nodes/{nodeId}/reminders ​

Creates or replaces the reminder (upsert). Requires read_write.

FieldRequiredMeaning
offset_daysnointeger 0–30, default 0 (the deadline day)
timeyesHH:MM (24 h), instance local time

Returns the stored reminder, the node's title and its deadline:

json
{
  "reminder": { "id": "r1", "map_id": "abc123", "node_id": "n_1", "offset_days": 1, "time": "09:00",
                "day": "2026-08-14", "fires_at": "2026-08-14 09:00", "fired": false },
  "node_title": "Draft the copy", "deadline": "2026-08-15"
}

Errors: the node has no deadline → 400 (set one via POST …/nodes/{nodeId} first), the computed time is already in the past → 400, unknown node → 404.

POST /api/kb/v1/maps/{id}/nodes/{nodeId}/reminders/{rid}/delete ​

Removes the reminder. Someone else's reminder is 404.

Delivery for both: the server checks every minute and sends a reminder notification to the bell and by e-mail (e-mail is on by default for this type and goes out even in daily-digest mode). After an outage, reminders older than KB_REMINDER_CATCHUP_H hours (default 48) are logged instead of sent. See Notifications.

Pages ​

HTML artifacts of the assistant (see Pages in the assistant). Through the API the client (agent) writes the whole HTML itself; the server enforces the size cap (KB_PAGE_KB, default 300 kB), the per-user count (KB_PAGES_MAX) and ownership (someone else's page is 404). KB_PAGES=0 → every path is 404. The response is always { page: { id, title, status, share_url, team_visible, size_kb, updated } } (status: ceka queued / pise being written / hotovo ready / chyba failed; share_url empty without a public link).

GET /api/kb/v1/pages · GET /api/kb/v1/pages/{id} ​

List (without HTML) · one page including html.

POST /api/kb/v1/pages ​

{ title, html, team_visible? } — creates a finished page from a complete HTML document (read_write scope).

POST /api/kb/v1/pages/{id} ​

{ html?, title? } — a new version (the previous one stays restorable in the app) and/or a rename.

POST /api/kb/v1/pages/{id}/share ​

{ action, email? } = link_on · link_off · link_new · team_on · team_off · user_on / user_off (+ email of a member; the response carries shared_with = e-mails). The public link is …/p/<token> (32 characters, anyone without an account; served with CSP sandbox, noindex, no cache).

DELETE /api/kb/v1/pages/{id} ​

Deletes the page (cannot be undone).

/api/kb/v1/tasks — removed ​

The task endpoints (GET/POST /v1/tasks, POST /v1/tasks/{id}) were removed and now return 410 Gone. In killBottleneck a task is not a separate record: a task is a node with an assignee (owner) or a deadline. New work = a new node. Create and update work through /v1/maps/{id}/nodes (MCP: add_nodes, update_node); a node completes by setting its status to done.

A worked example ​

bash
KEY="kb_user_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
HOST="http://localhost:8090"

# 1) find a map
curl -s -H "Authorization: Bearer $KEY" "$HOST/api/kb/v1/maps"

# 2) read it — and keep `updated`
MAP=abc123
UPDATED=$(curl -s -H "Authorization: Bearer $KEY" "$HOST/api/kb/v1/maps/$MAP" \
          | python3 -c 'import json,sys; print(json.load(sys.stdin)["updated"])')

# 3) add two goals under the apex
curl -s -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"base_updated\":\"$UPDATED\",\"items\":[
        {\"title\":\"Draft the copy\",\"deadline\":\"2026-08-15\"},
        {\"title\":\"Shoot the photos\"}]}" \
  "$HOST/api/kb/v1/maps/$MAP/nodes"

# 4) "this is the priority" = plan it for today (re-read `updated` first — the map just changed)
NODE=n_1
UPDATED=$(curl -s -H "Authorization: Bearer $KEY" "$HOST/api/kb/v1/maps/$MAP" \
          | python3 -c 'import json,sys; print(json.load(sys.stdin)["updated"])')
curl -s -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"base_updated\":\"$UPDATED\",\"planned_on\":\"$(date +%F)\"}" \
  "$HOST/api/kb/v1/maps/$MAP/nodes/$NODE"
# → 200, the goal is in My day under "Today"; its deadline did not move

# 5) a field the API does not know is an error, never a silent no-op
curl -s -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"base_updated\":\"$UPDATED\",\"priority\":\"high\"}" \
  "$HOST/api/kb/v1/maps/$MAP/nodes/$NODE"
# → 400 {"error":"Unknown fields: priority. Allowed fields: title, status, description, deadline,
#    planned_on, owner, … There is no \"priority\" in killBottleneck — priority is expressed by
#    the plan planned_on (WHEN you intend to work on it, today to +7 days). …"}

Error codes ​

See Error codes for the full table.

Open source under the MIT license · © Tengo s.r.o.