Create a BlackOps note, or update one in place when source_id resolves to a known note. Requires content_markdown (or transcript/conversation). Prefer this over post_notes_write — richer metadata, dedup, search/list visibility, auto-vault-sync.
source_id is the idempotency key: pass it (content hash, agent-defined string, or note UUID) so repeat calls update instead of forking. Already know the note? Use patch_notes with id instead. Check response warnings — an auto-suffixed slug ("my-note-2") with code SLUG_COLLISION means an intended update forked instead.
Site is OPTIONAL (resolves explicit → account default intake → the user's only site); pass domain/site_id only for a note tied to one site.
BRAINS: pass a named brain's UUID as brain_id — the server derives site/target/folder from it, and this always skips auto-routing below. Never infer site_id or guess target_id from topic keywords. brain_alignment in the response confirms the compile will pick the note up.
WITHOUT brain_id, a site that has opted into brain auto-routing resolves one itself instead of leaving the note unfiled with a guess-and-ask: an Auto verdict files the note straight into that brain's Triage lane (routing: { band: "auto", filed: true, brain_id, brain_name, probability, verdict_id }); a Suggest or No-home verdict saves the note unfiled and the response carries needs_brain_choice — present its question and up to 3 options (each with a one-line reason) as ONE single-choice question, the way your host renders a question or choice card if it has one, alongside the also entries ("Leave unfiled" / "Create a new brain"), then call resolve_with (patch_notes with the chosen brain_id) with the pick. Never choose a brain from that list yourself. A site that has not opted in behaves exactly as before — the note is saved unfiled, no brain is queried. suggest_brain: true is a separate, unrelated opt-in: a keyword-based unassigned-brain match surfaced as suggested_brain, not auto-routing.
TAGS outside the vocabulary still apply and stay queryable, with an UNKNOWN_TAG warning naming it — ask the user before calling propose_note_tags.
VAULT SYNC is automatic but DEFERRED: the commit runs after the response, so sync is { status: "queued" }. The note IS saved — do NOT re-call. Confirm a landed commit with get_note, never vault_sync_queued_at; pass wait_for_sync: true only for commitSha/filePath inline. override_folder_path bypasses the workspace taxonomy, though a brain's source_folder_path still wins.
phase/priority/position are Big Board columns (High|Medium|Low for priority); phase is free text.
View input schema
{
"type": "object",
"properties": {
"site_id": {
"description": "Site UUID to scope this call to. Alternative to domain.",
"type": "string"
},
"domain": {
"description": "Site domain to scope this call to (e.g. example.com). Alternative to site_id.",
"type": "string"
},
"source_id": {
"description": "Idempotency key. A repeat call with the same source_id updates that note instead of creating a new one. A content hash, your own string, or a note UUID.",
"type": "string"
},
"conversation_id": {
"description": "Id of the chat conversation this note came from, stored on the note.",
"type": "string"
},
"conversation": {
"description": "A chat conversation to save as the note: { id?, title?, messages[] }. Used when content_markdown is not given.",
"type": "object",
"additionalProperties": {},
"properties": {}
},
"title": {
"description": "Note title, up to 200 characters.",
"type": "string"
},
"note_type": {
"description": "Note type: general, project, initiative, daily, reference, task or skill. Also steers which vault folder it syncs to.",
"type": "string"
},
"content_markdown": {
"description": "Note body in Markdown. Required unless transcript or conversation is given.",
"type": "string"
},
"transcript": {
"description": "Raw transcript text to save as the note when there is no Markdown body.",
"type": "string"
},
"excerpt": {
"description": "Short summary shown in note lists and search. null clears it.",
"type": [
"string",
"null"
]
},
"status": {
"description": "Note status: active (default), draft or archived.",
"type": "string",
"enum": [
"draft",
"active",
"archived"
]
},
"target_id": {
"description": "UUID of the vault target to sync the note to. Omit to let the server pick one (see assign_target).",
"type": [
"string",
"null"
]
},
"brain_id": {
"description": "UUID of the brain this note belongs to. The server derives the site, vault target and folder from it.",
"type": "string",
"format": "uuid"
},
"phase": {
"description": "Big Board phase column for the note, free text (max 100 characters).",
"type": "string"
},
"priority": {
"description": "Big Board priority: High, Medium or Low.",
"type": "string",
"enum": [
"High",
"Medium",
"Low"
]
},
"position": {
"description": "Big Board rank within its column. Usually left unset; a board sets it on drag.",
"type": "string"
},
"tags": {
"description": "Tags for the note. Tags outside the site vocabulary still apply, with an UNKNOWN_TAG warning.",
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"description": "Free-form key/value data stored with the note.",
"type": "object",
"additionalProperties": {},
"properties": {}
},
"assign_target": {
"description": "Default true: when target_id is omitted, pick the best-matching vault target for the note. False leaves the note without one (or keeps its existing target).",
"type": "boolean"
},
"auto_sync": {
"description": "Default true: commit the note to its vault target after saving. False saves it without syncing.",
"type": "boolean"
},
"override_folder_path": {
"description": "Vault folder to write the note into, bypassing the workspace folder rules. A brain's own source folder still wins.",
"type": "string",
"minLength": 1
},
"wait_for_sync": {
"description": "Default false. True holds the response until the vault commit lands, so it returns commit_sha and file_path.",
"type": "boolean"
},
"suggest_brain": {
"description": "Default false. True checks whether the note matches a brain and returns it as suggested_brain, without filing it.",
"type": "boolean"
},
"confirm": {
"description": "Pass true to confirm this action once the user has approved it.",
"type": "boolean"
},
"triage_state": {
"description": "Set to 'pending' to file this note into a brain's Triage lane (unreviewed) instead of committing it to the vault right away. Leave unset for an ordinary note.",
"type": "string",
"enum": [
"pending",
"promoted",
"dismissed",
"expired"
]
},
"allow_secrets": {
"description": "Set true to store content that looks like a credential (API key, token, private key), which is otherwise refused with SECRET_DETECTED. Only when the user asked to store that exact value.",
"type": "boolean"
}
}
}