---
title: Notes databases for agents (MCP and REST)
description: 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.
section: cloud
order: 162
audience: [user, builder, agent]
sources: [services/nodejs-cloud/lib/globe/mcp/db-tools.ts, services/nodejs-cloud/lib/globe/mcp/db-calls.ts, services/nodejs-cloud/lib/globe/mcp/db-routes.ts, services/nodejs-cloud/lib/globe/databases/index.ts, services/nodejs-cloud/contracts/openapi/workspace-v1.json]
features: [cloud.workspace]
---

[Notes databases](/docs/cloud/globe-databases.md) are tables whose rows are notes. Agents get them on the
[workspace MCP server](/docs/cloud/workspace-mcp.md) (`/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](/docs/developers/rest.md)).

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.

```json
{
  "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:

````markdown
## 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.
