We use cookies to measure site usage with Google Analytics. We only turn that on if you say yes. See our Privacy Policy.

Documentation

Account-Scoped Notes

Notes are account-level intake — query and capture across all your sites with no site argument, and use site scope only as an optional affinity filter.

Notes in BlackOps follow one principle: intake is account-level, output is site-level. Your knowledge — captures, feature ideas, bug reports, references — belongs to you, not to whichever site a session happened to be pointed at. Publishing (posts, tweets, pages, campaigns) stays scoped to individual sites.

Overview

Before this change, every note query and capture required a site. For accounts with multiple sites, that fragmented knowledge silently: a note logged while working on one site was invisible to queries scoped to another, even though both belonged to the same person.

Now the notes surface is account-scoped by default:

  • Queries span your whole account. list_notes with no domain or site_id returns notes from every site you can access, in one result set.
  • Site scope is an affinity filter, not a requirement. Pass domain or site_id when you want to narrow to one site's notes — it's optional.
  • Capture works without a site. post_notes resolves where a note lands: an explicit site if you passed one, otherwise your account's default intake site, otherwise your only site.

The default intake site

Multi-site accounts choose one site as the home for site-less captures with patch_account_settings:

{
  "default_intake_domain": "yoursite.com"
}

or by UUID with default_intake_site_id (pass null to clear). Read the current value with get_account_settings.

The default intake site decides which workspace record owns the note and which connected vault receives the synced markdown file. It changes nothing about where the note is visible — account-scoped queries always see all of your notes.

Usage

List everything across your account:

// list_notes — no site argument
{ "tags": ["feature"], "status": "active", "limit": 50 }

Narrow to one site when it matters:

{ "tags": ["feature"], "domain": "yoursite.com" }

Capture without thinking about sites:

// post_notes — lands on your default intake site
{ "title": "Idea: weekly digest", "content_markdown": "..." }

The list_notes response includes a scope field ("account" or "site") so callers can tell which mode served the query.

Configuration

SettingToolEffect
default_intake_site_idpatch_account_settingsSite that receives note captures made without an explicit site
default_intake_domainpatch_account_settingsSame, addressed by domain

If no default is set and you have multiple sites, post_notes without a site returns an error listing your sites and how to set the default — it never guesses.

Related

  • Note Taxonomy — tag vocabulary and folder routing for synced note files

The default site is stated back to you

The default intake site is also the default for writes. Unless you name another site, post_notes, post_posts and create_brain go to it, and every one of those responses carries site_used (id, name, domain, and whether it came from explicit, default or only_site).

  • get_ai_context returns default_site with the rule sentence: "Unless the user names another site, writes go to benenewton.com."
  • Naming a site that differs from the default still works. The response adds a CROSS_SITE_WRITE warning so a wrong guess is visible.
  • Notes are site-agnostic: any note can be filed into any brain you own, regardless of which site the note or the brain lives on.
  • New brains with no vault target inherit the site's active vault target. Pass db_backed: true to opt out.
  • list_brains and get_brain return vault_target_id and has_vault_target.
  • get_site_repair_report lists notes with no vault file and brains with no vault target. It only reports; it never moves or backfills anything.
Want this page as machine-readable markdown? GET /docs/features/account-scoped-notes.md