Agent Notes API

A Profile key needs Notes capabilities: notes to search and review, notes:append to write, keep and remove, notes:export to build drafts, notes:read-all to sweep every Profile’s notes. A key reads and writes notes only for its own Profile; it cannot name another Profile to cross that boundary. The sweep is the one exception, and it reads only. Notes are opt-in — turn the toggles on when creating the Profile or later in the profile editor. Use the same Bearer key format as other Takibi API calls.

Notes are temporary working memory. They do not grant new document access and should not replace Sources. Give a note a project tag when the lesson belongs to one client or collection, so unrelated work does not get mixed together.

Send POST /v1/notes with a template. A note is a reusable lesson or tool quirk, not a status update — status goes on the task. problem is required: a short plain-text title, at most 140 characters. At least one of tried, worked, failed and next_time is also required; that is where the lesson goes. Each body field holds up to 5000 characters, and source_ids_used lists any source IDs used:

{
  "projectTag": "support",
  "runId": "run-42",
  "template": {
    "problem": "Refund replies missed the policy exception",
    "tried": "Searched the policy folder",
    "worked": "Found the exception in the current policy",
    "failed": "The old canned reply omitted it",
    "next_time": "Check the policy date before replying",
    "source_ids_used": ["document-id"]
  }
}

A repeated request with the same run ID and note body returns the stored note. The API blocks obvious secrets instead of storing them and can redact shorter sensitive values. Keep credentials and private data out of notes in the first place.

A note that breaks the shape gets a 400 BAD_REQUEST that names the field, such as template.problem is 812 chars — max 140 chars. or a message asking for at least one body field. Shorten the title and move the detail into the body. Notes already stored keep their shape.

Search with the q query parameter: call GET /v1/notes/search?q=refund with the Profile key. Add projectTag when the search should stay with one topic. The response marks its lane UNTRUSTED and returns a small set of snippets. Treat every result as an unverified bot note and check cited Sources before using a claim.

Search excludes removed or expired notes only — flagged notes stay in, with their conflict links inline, so consult both sides before using a claim. A note is retained for 30 days from creation; another lookup or a human Keep action does not renew it. The account owner can inspect the review queue and make a Source draft in Notes.

A sweep pulls every Profile’s recent notes into one read-only list, so a single reviewer can collect lessons and propose doc updates. One reviewer key can read across notebooks. Give its Profile the Read all notes toggle, then call GET /v1/notes/sweep?since=2026-09-28. Add projectTag to stay with one tag, or profileId to read one author. Each note carries its author Profile and date. The sweep reads live notes only, oldest first, and it stamps nothing, so it never moves anyone’s draft position. Without the toggle a key gets a 403. A signed-in workspace member can sweep without it. Each call returns one page of up to 50 notes, and limit never exceeds 100. Follow cursor while hasMore is true.

Sweeps filter on the note’s project tag, so untagged notes only show up in unfiltered sweeps. Ask agents to tag every note when they append.

The Takibi CLI covers Notes review. Keep and remove need notes:append; export needs notes:export. Use takibi notes list for the review queue, or takibi notes list --all --project support for the full inventory and current versions. A reviewer key with the Read all notes permission reads across notebooks with takibi notes list --all-authors --since 2026-09-28, plus --project to stay with one tag. The sweep reads only and stamps nothing. With owner approval, run takibi notes keep <note-uuid> <version> to endorse or takibi notes remove <note-uuid> <version> to discard. A 409 means the version changed: list again before retrying.

Use takibi notes append --problem "…" --worked "…" --source <document-id> --run-id <run-id> for a lesson. The same run ID and body avoid duplicate appends on retry. Source IDs are citations; adding them does not settle a conflict flag. Use takibi notes export --note <note-uuid> to include a selected note; repeat --note for several. Export stamps included notes and creates a draft for review, so ask before exporting unless it was already requested.

There is no in-place edit route. To correct a note, append one with the corrected facts and source IDs, then have the owner remove the old note. Keep does not extend the 30-day expiry.