Skip to content
Docs menu

Notes databases for agents (MCP and REST)

Let an agent create a database (table) inside a Notes page with its columns and rows, query it, change its schema and views, import CSV, and delete it cleanly, through the workspace MCP server or its REST twin.

View .md

Notes databases are tables whose rows are notes. Agents get them on the workspace MCP server (/workspace/mcp, or /workspace/mcp/globe for Notes alone) so that a table is a real database the user sees and edits in the page, never a markdown table. The same tools answer over REST under /api/v1/databases (REST API).

An inline database is what the editor makes: a database whose rows live in a folder next to the note, plus a base block in the note's markdown (database: <id> and view: <id>). globe_database_create writes both, so the page shows the table at once, with no "Make it a Notes database" click and nothing to paste.

Create an inline database with 3 properties and 5 rows

One call. The note is created if its path is new.

{
  "name": "globe_database_create",
  "arguments": {
    "title": "Plan tasks",
    "vault": "me",
    "note": "Projects/Plan",
    "position": { "after_heading": "Tasks" },
    "properties": [
      { "name": "Task", "type": "title" },
      { "name": "Status", "type": "select", "options": ["Todo", "Doing", { "name": "Done", "color": "green" }] },
      { "name": "Due", "type": "date" }
    ],
    "rows": [
      { "title": "Write spec", "values": { "Status": "Done", "Due": "2026-11-02" } },
      { "title": "Build it", "values": { "Status": "Doing", "Due": "2026-11-09" } },
      { "title": "Test it", "values": { "Status": "Todo", "Due": "2026-11-12" } },
      { "title": "Ship it", "values": { "Status": "Todo", "Due": "2026-11-20" } },
      { "title": "Celebrate", "values": { "Status": "Todo" } }
    ]
  }
}

The answer names the database id, the properties and the note's new version. The note now reads:

## Tasks

```base
database: 0193…
view: k3x9q2ab
```

The same over REST: POST /api/v1/databases with that object as the body.

position is one of after_heading (directly under the heading with that text), after_text (after the paragraph or list that contains the text) or end (the default). Leave out note for a full-page database. rows takes up to 100; a bigger table goes in with globe_row_create, 100 rows a call. Set dry_run: true to check everything and write nothing.

The answer has the page's url (the note when the database is inline, else the database's /globe/db/<id> page), the database's url and each row's url. Everything that can be refused (property values, an oversized or secret-looking row body) is checked before the first write, so a refused create leaves nothing behind. If a row still fails while it is written, the other rows are saved, the block is still embedded in the page, and the answer lists which rows were not written and why. A row title with : or ? is saved with those characters replaced, not refused.

The tools

Tool Does
globe_database_create Create a database (table), inline in a note or as a page, with properties, rows and a first view
globe_database_get, globe_database_list Properties with types and option names, views, row count and version; list databases
globe_database_update Title, description, lock; add, rename, retype and delete properties; add, rename, remove select options. Renames and removals reach the rows
globe_database_delete Remove the inline block from the page that holds it, trash the rows (rows: "keep" leaves them as notes), delete the database
globe_database_import CSV or a markdown table, as a new database (types are guessed) or into an existing one; up to 500 rows
globe_database_validate Check a pasted base block or .base file and get its warnings
globe_row_list Rows with filter, sort, view, q and paging; values by property name
globe_row_create Up to 100 rows a call; replace: true trashes the existing rows first
globe_row_update One row, or updates: [{row, values}] for up to 100; all are checked before any is written
globe_row_delete row, rows (up to 100) or all: true to clear the table; rows go to the trash
globe_view_create, globe_view_update Table, board, list, gallery, calendar, timeline and chart views, by property name
globe_note_property_update Set or remove a note's properties by name (a row is a note, so this edits cells too)

Every write takes expect_version where it changes something that exists (the version a read answered) and refuses when it changed since. Creates take idempotency_key. Reads take format: "json".

Property types

title (one per database; "Name" is added when you give none), text, number (format: number, percent, currency; decimals; currency), select, multi_select, status (options grouped todo, in_progress, done), date (time: true for a time), person (member emails or ids), checkbox, url, email, phone, files (URLs), relation (database: an id or exact name), created_time, created_by, last_edited_time, last_edited_by (worked out, never set), formula (formula: the formula language of Notes) and rollup. button properties run an automation and are set up in the UI. An unknown type is refused with this list.

Options are names or {name, color, group}. A row value must be one of them: a wrong one is refused with the valid options, or pass add_options: true to create them, as typing one in the UI does.

Cell values: text, url, email, phone a string; number a number (a numeric string is accepted); select and status an option name; multi_select, person, files, relation a list of strings; checkbox true or false; date "2026-11-20", "2026-11-20T09:30" or {"start","end"}. null clears a cell.

Filter and sort

filter has the shape of a view's filter, with property names: {"property":"Status","op":"eq","value":"Done"}, or {"and":[…]} and {"or":[…]} of those (three levels). Operators depend on the type (eq, neq, contains, gt, before, empty, not_empty, in_group and more); a wrong one is refused with the ones the type takes. sort is ["Due desc", "Name"] or [{"property":"Due","direction":"desc"}]. Over REST, filter and sort go in the query string as JSON or the shorthand.

Wrapped columns

Long text is wrapped onto several lines instead of being cut off. Text columns wrap by default when created through MCP (a rule, an example, evidence); wrap: false on a property keeps one line, wrap: true wraps any column, and wrap_all: true wraps the whole first view. Views take wrap (all columns) and wrap_columns (names) in globe_view_create and globe_view_update. The inline block shows the same "Wrap column" menu entry as the full-page database, and a wrapped row grows to fit its text.

Notes with frontmatter, and base blocks

  • globe_note_write reads a YAML frontmatter block at the top of the body as the note's properties, as the zip import does, and takes a properties object that wins over it. Existing properties not named are kept.
  • Writing a markdown table to a note answers with a hint toward globe_database_create.
  • A base block the agent writes is checked: a block naming a missing database, one that does not parse, or a pasted .base file (which is not a Notes database until converted) is reported in the answer of globe_note_write and globe_note_edit. globe_database_validate runs the same check on its own.

Access

The tools use the caller's own rights, as the note tools do: a personal key reaches that member's personal vault and the org vault; a team or service key reaches shared vaults only; writing to the org vault needs the org permission; a connected app needs the globe:write scope. A database someone else cannot read answers "No such database" over MCP and 404 over REST.