piyaz_note
Project notes: the team's shared knowledge base, in the same folder tree humans see in the web UI.
Note params accept a noteRef ('DLK-N12'), a note UUID, or a slug together with project; responses emit refs. Types: guidance=constraints auto-injected into matching task bundles; reference=specs and docs, read on demand by heading; knowledge=agent-maintained wiki and memory. Write back what you learn, durable constraints, gotchas, and decisions belong in notes so the next agent starts smarter. create=1-10 notes (title required; body, folder, type, summary, tags, category, feed params). Agent-created notes land visibility=team, feed_mode=none: teammates' agents can search them immediately, nothing auto-injects until feedMode is deliberately set (all/categories/tags/tasks; feedTaskIds accept taskRefs). Idempotent by exact (folder, title): dupes return as deduped. read=meta header by default; fields=[...] for exact values plus updatedAt (the ifUpdatedAt token); heading='...' for one section; fields=['revisions'] for the snapshot list; revision=N for one snapshot. The full body only via fields=['body'], prefer heading reads. edit=1-20 ordered ops, atomic: str_replace/append/set on body (oldStr must match exactly once; the error names the count), set for title/summary/folder/type/category/tags/feedMode/feedCategories/feedTags/feedTaskIds. visibility, locked, and agent_writable are not editable here, request_share is the agent's only path toward team visibility for a private note, and notes with agent_writable=false reject every agent write (reads and search still work). list=the project's folder tree (refs, titles, folders, types, feed modes). move=one note into a folder, or folder+destParent (+newLeaf) to re-parent or rename a whole folder subtree, keep the tree organized for humans. delete=preview by default, re-call preview=false; restore recovers a trashed note (use the UUID from the delete response). An overwritten body is recoverable: fields=['revisions'], then revision=N, then set body. link/unlink=deliberate note-task relations (kind reference|spec_of); mention rows derive from [[refs]] in the body, write the ref into the body instead. search=a full noteRef ('DLK-N12', case-insensitive) resolves that note, else fuzzy within one project: title/summary/tag substring first, then ranked full text over title and body. Team notes plus your own private notes, any feed mode. A ref that resolves nothing falls back to the fuzzy tiers. Next: read heading='...' for the matching section instead of the full body.
Actions
| Action | Purpose |
|---|---|
create | 1-10 notes, idempotent by (folder, title) |
read | meta / fields / heading section / revision snapshot |
edit | ordered ops |
list | the folder tree |
move | note to folder, or folder subtree re-parent/rename |
delete | preview by default |
restore | recover a trashed note |
request_share | ask a human to make a private note team-visible. link/ |
link | note-task relation (reference|spec_of) |
unlink | note-task relation (reference|spec_of) |
search | a noteRef ('DLK-N12') resolves that note, else title/summary/tag substring plus ranked full text in one project |
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
action | "create" | "read" | "edit" | "list" | "move" | "delete" | "restore" | "request_share" | "link" | "unlink" | "search" | Yes | create=1-10 notes, idempotent by (folder, title). read=meta / fields / heading section / revision snapshot. edit=ordered ops. list=the folder tree. move=note to folder, or folder subtree re-parent/rename. delete=preview by default; restore=recover a trashed note. request_share=ask a human to make a private note team-visible. link/unlink=note-task relation (reference|spec_of). search=a noteRef ('DLK-N12') resolves that note, else title/summary/tag substring plus ranked full text in one project. |
destParent | string | No | move (folder form): new parent path ('' = root). Present destParent switches move to folder-subtree mode. |
fields | ("title" | "body" | "summary" | "folder" | "type" | "visibility" | "feedMode" | "feedCategories" | "feedTags" | "feedTaskIds" | "tags" | "category" | "agentWritable" | "locked" | "links" | "revisions")[] | No | read only: exact raw values for the named fields plus updatedAt (the ifUpdatedAt token). fields=['body'] is the only full-body read; prefer heading. |
folder | string | No | move: the destination folder for a note ('' = root), or the source folder path when moving a folder subtree. |
heading | string | No | read only: one markdown section by its heading text (case-insensitive, fence-aware). A miss lists the available headings. |
ifUpdatedAt | string | No | edit only: optimistic-concurrency precondition from a prior read. On mismatch the call fails with the fresh updatedAt and version, re-read, then retry. |
kind | "reference" | "spec_of" | No | link/unlink: relation kind. spec_of=this note is the task's spec. reference=supporting material. mention rows derive from [[refs]] in the body and are not managed here. |
limit | integer | No | search only: hit cap (default and max 20). |
newLeaf | string | No | move (folder form): replacement folder name; a rename is a move to the same parent with a new leaf. |
note | string | No | noteRef ('DLK-N12'), note UUID, or slug (slug needs project). Required for read, edit, move (note form), delete, restore, request_share, link, unlink. |
notes | object[] | No | create only: 1-10 notes to create in one atomic call. |
onDuplicate | "skip" | "error" | No | create only. skip (default): items whose (folder, title) already exists create nothing and return as 'deduped'. error: reject the whole batch before any write. |
operations | object[] | No | edit only: 1-20 operations applied in order, atomically; one failure rolls back all. |
preview | boolean | No | delete only. true (default)=impact summary (links, revisions). false=execute the soft delete; restore undoes it. |
project | string | No | Project identifier ('DLK') or UUID. Required for create, list, and search; also scopes a slug-form note param. |
query | string | No | search only: a full noteRef ('DLK-N12', case-insensitive) resolves that note, falling back to the fuzzy tiers when it resolves nothing; otherwise title/summary/tag substring plus ranked full text where the last term prefix-matches. |
revision | integer | No | read only: one revision snapshot by version number (see fields=['revisions']). The recovery read for an overwritten body. |
task | string | No | link/unlink: the task endpoint, taskRef ('DLK-42') or UUID. |
Last updated