Tools

Get a board

get_board Reads

One board: its blocks, whether it is published, and its address.

List boards

list_boards Reads

Every board of the base, in sidebar order, with whether each is published and its address.

Look at a board

screenshot_board Reads

A picture of a board's body as a visitor reads it — its text, pictures, value boxes and widgets, drawn from the rows they read now — 1280 pixels wide. A picture from a URL draws as not loaded. Whether the board is published changes nothing: it stays as it was. Nothing is written and no run is fired.

More

A board taller than 1200 pixels comes back one page at a time: the answer says page of pages, and page: 2 is the next 1200 pixels, and so on to the end. Each call draws the board afresh. A page past the last is refused, naming how many there are. theme picks light (the default) or dark. thrown is anything a widget threw while it drew. When it cannot be drawn the answer is {"screenshot": {"unavailable": <reason>}}.

Search boards

search_boards Reads

Boards whose title holds q — the sidebar's filter.

Create a board

create_board Adds

Create a board, at the end of the list or after after. Every board is at the top level; one board links to another with a mention, never by holding it. It starts unpublished. The id is yours to mint.

Restore a board

restore_board Adds

Bring a board out of the trash, at the end of the list, as it was: a published one is served at its address again. list_trash names what is there.

Delete a board

delete_board Changes

Trash a board with everything on it. restore_board brings it back; list_trash with board shows it. While it is in the trash its address answers not-found. One with nothing in it that nothing but your own open sitting ever touched is deleted outright instead, and has no way back.

Edit a board

edit_board Changes

Apply a batch of block operations to one board — the only way to write, delete or reorder a block. One call is one transaction.

More

A heading is a heading block: its text, and level 1, 2 or 3 in props. A set at ["type"] turns a paragraph into a heading or back and keeps the block's id — send the level with it.

A value box is a text chunk {"value": {"sql": …, "description": …}}: one cell of a query, drawn live inside a sentence. Always both fields, the description one line. Rows on a board are a widget's job: make one with create_widget and put a widget block on the board.

A text chunk may instead be {"mention": "<board id>"}: a live board of this base, drawn as its current title. It stores no title, and anything else it names is refused with mention_invalid. A board is never a block of another board.

Marks sit flat on a chunk: bold, italic, underline, code, strike, link, and color for the ink and background for a wash behind it. A colour is a name, never a hex — grey, brown, orange, yellow, green, blue, purple, pink or red — and the two are independent.

An image block's props are exactly one of {"path": "/files/…"}, a picture in the base's files, or {"url": "https://…"}, one on the web. A path is copied into the block and shrunk to 4000 px, so moving or deleting the file later changes nothing; it is stored as image, width and height, and the answer's stored says so. A URL is drawn live and breaks when its site does. PNG, JPEG, GIF and WebP only. To put a local file on a board, request_upload it and name the path you get back.

The description is for the person, not for you: what the query asks, in the words someone would use to ask for it — "Tasks still open, newest first". The SQL is physical names in hex and nobody can read it, so this is the only readable record of what the block draws, and a block saved without one is refused.

Lock or unlock a board

set_board_lock Changes

Lock a board, or unlock it. A locked board refuses every edit to its title and its body — edit_board answers board_locked — for everyone, until somebody unlocks it. Moving, trashing and publishing it still work. Unlock only when the person asked you to change that board.

Move a board

move_board Changes

Put a board after after in the list, or first when after is null.

Publish or unpublish a board

set_board_published Changes Reaches outside

Publish a board, or unpublish it. Published, anyone with its link reads it at /public/<name>-<token>, signed in or not, and it is listed on the base's Public home. The answer's path is that link. The first publish mints the token, and it never changes after: unpublishing stops serving it, and publishing again brings the same one back. Only the token is read, so a rename never breaks a link already handed out. Publish only when the person asked for the board to be public.

Get a table

get_table Reads

One table and every column on it, with each column's type.

List a table's rows

list_rows Reads

Rows of one table, by limit and offset. To filter, sort, group or join, write SQL — run_sql. The database screen's own filter is the UI's and adds nothing an agent holding SQL does not already have.

List tables

list_tables Reads

Every live table in the base.

Run read-only SQL

run_sql Reads

Run read-only SQL against this base's tables. Ordinary Postgres — joins, GROUP BY, date_trunc, window functions, now().

More

Names are physical and derived from ids, so a rename never breaks a query: a table is the view "v_<hex>" (get_table gives the ids; the hex is the uuid without dashes) and a column is "c_<hex>". Select id when you want the rows to be writable or numbered. A select/multi_select value is an option id, not its label.

Writes are refused by the database itself, not by a check here: there is one role per base, granted SELECT on its views and nothing else. Use write_rows to change anything.

Add a column

add_column Adds

Add a column to a table.

Create a table

create_table Adds

Create a table and its columns.

Restore a column

restore_column Adds

Take a dropped column back under the same id, with every value it held. Every stored query naming it runs again with no edit.

Restore a table

restore_table Adds

Bring a trashed table back, if its name is still free.

Change a column's type

change_column_type Changes

Change a column's type. Refused, naming the rows that stopped it, when a value would not survive the cast.

Delete a column

delete_column Changes

Drop a column. Never refused — every query naming it stops running and says so. restore_column takes it back, with its values — and so do undo, to the place it held, and reverting the table to a version from before the drop.

Delete a table

delete_table Changes

Trash a table. restore_table brings it back — unless the table held no rows and nothing but your own open sitting ever touched it, which is deleted outright and has no way back.

Rename a column

rename_column Changes

Rename a column. A label edit — nothing in the database moves.

Rename a table

rename_table Changes

Rename a table. Its columns and rows are untouched.

Write rows

write_rows Changes

Insert, set, delete or restore rows of one table. One call is one transaction and one undo step, however many rows it touches. A new row lands last; rows are in # order and cannot be placed.

Get a widget

get_widget Reads

One widget: its declaration, its screen source and its build hash. An empty source is a stub someone made from the menu — a name waiting for you to write its screen with update_widget.

Get a widget's data

get_widget_data Reads

Run every data query a widget declares and return the rows.

List a widget's errors

list_widget_errors Reads

What went wrong with a widget, newest first, each with its kind: undeclared_data and undeclared_run for a read or run its declaration never named, automation_gone for a declared run whose automation has left, render for a screen that threw, compile for a save the compiler refused. A run's own failure is not here — get_run has it. limit is capped at 200.

List widgets

list_widgets Reads

Every live widget in the base, by name and size.

Look at a widget

screenshot_widget Reads

A picture of a widget as it looks now, drawn from the rows it reads now — the same picture, four sizes and thrown a save answers with, without saving. For a widget whose rows may have changed since it was last saved; a save already answers with one. Nothing is written and no run is fired: while it draws, every run is refused not while previewing. theme picks light (the default) or dark. A stub answers {"screenshot": null}, and one that cannot be drawn {"unavailable": <reason>}.

Create a widget

create_widget Adds

Create a widget from a declaration and a TypeScript screen. The screen is compiled on the way in; a refusal names every violation by line.

More

Say why in change_description — one line, in words the person would use: "Shows the week's total above the chart". It is the line the widget's history shows for this version, and a source saved without one is refused (422 change_description_required).

A screen imports react and @moonwalk/widget and nothing else, and exports its component as the default export:

import { publicUrl, useFocus, useQuery, useRun, useRunResult, useScroll, useTheme } from '@moonwalk/widget'

export default function Tasks() {
  const tasks = useQuery('tasks')      // a key of declaration.data
  const move = useRun('move')          // a key of declaration.runs
  const collect = useRunResult()       // a run answered `strt`, asked again by its id
  const theme = useTheme()             // 'light' or 'dark'
  const scroll = useScroll()           // 0 → 1 as the page scrolls this block past
  const focus = useFocus()             // false while the reader is in another window
  if (!tasks.rows) return <p>Loading…</p>
  return (
    <>
      <audio src={publicUrl('theme.mp3')} controls />  {/* /files/Public/theme.mp3 */}
      <ul>{tasks.rows.map((t) => <li key={t.id}>{String(t.title)}</li>)}</ul>
    </>
  )
}

The <Screen> provider is mounted around it for you; a screen never renders one. useQuery gives {rows, broken} and nothing that writes. There is no fetch, no token and no storage — the broker is the only way in or out.

useRun gives a function resolving to {run_id, status, returncode, output}. status is fin (it ended) or strt (still going past the server's 3-second wait — not a failure). fin does not mean it worked: check status === 'fin' && returncode === 0. rej never reaches a screen — a refused run rejects the promise instead.

output is the JSON object the automation's last step returned — its ReturnType — so read the field you want: run.output.message. It is null while strt and when the last step failed, and past 16 KB it is {"$over": <bytes>}: a run answers, it does not hand over a dataset. get_widget reports each run's output_schema. A run answered strt can be collected later: useRunResult()(run.run_id) resolves the same shape.

A run may take a file. A trigger property marked {"type": "string", "format": "file"} takes one, and a screen passes a File at the top level of input — useRun('import')({ book: file, language: 'en' }). It goes as bytes in the one request, is saved into /files/Uploads/, and the step is handed the path it was saved at. Nothing in the SDK is new for it: an <input type="file"> and the File it yields.

This is the one thing you cannot do yourself — fire_automation names a path because MCP carries no bytes, and the browser is the caller that sends them. A file past 100 MB is refused, 413 too_large.

A screen loads a file from the base's Public/ folder by naming it: <audio src={publicUrl('theme.mp3')} controls /> plays /files/Public/theme.mp3. Images and fonts load the same way. Only files in Public/ can be named like that, and anybody can open them, signed in or not, so moving a file in is publishing it. The screenshot a save answers with does not load them.

A declaration is data and runs. A widget reads and runs, and does nothing else — there is no way to write a row through a query, so a data entry has no mode and a declaration carrying one is refused.

Each declaration.data entry is two fields: sql and description.

The SQL is read-only Postgres over this base's views — "v_<hex>" for a table and "c_<hex>" for a column, both derived from ids, so a rename never breaks one. Alias every column to the key the screen reads, and select id when the screen needs a row to name in a run.

The description is for the person, not for you: what the query asks, in the words someone would use to ask for it. The SQL is hex and nobody can read it, so this is the only readable record, and an entry without one is refused.

Each declaration.runs entry is the screen's name for it → the id of an automation that already exists in this base. Its trigger must be manual: a cron or webhook trigger fills its own payload, so a screen has nothing to supply. useRun('move')(input) fires it with input as the trigger's output, so input has to fit that trigger's output_schema — read it back off get_widget, which reports each run as {automation_id, automation_name, input_schema, output_schema}, the last being what the run's output holds. Build the automation first, then bind it; there is no way to make one from here.

The box is fixed. A screen draws into exactly width × height CSS pixels and nothing grows to fit it: anything taller scrolls inside the box, so design to the number. size is its own field beside the declaration — {"width": 480, "ratio": "4:3"} — and a resize is that alone. A new widget with a screen names its size (422 size_required without one); only a stub is given the smallest. The 16 boxes:

320 wide: 16:9 is 320×180, 4:3 is 320×240, 3:4 is 320×427, 2:3 is 320×480
480 wide: 16:9 is 480×270, 4:3 is 480×360, 3:4 is 480×640, 2:3 is 480×720
640 wide: 16:9 is 640×360, 4:3 is 640×480, 3:4 is 640×853, 2:3 is 640×960
960 wide: 16:9 is 960×540, 4:3 is 960×720, 3:4 is 960×1280, 2:3 is 960×1440

Every save that changes the screen, the declaration or the size answers with a screenshot of the widget as drawn, from its real rows, and four sizes: clientWidth and clientHeight are the box, scrollWidth and scrollHeight the content, the page's or a div's that fills the box and scrolls or clips, whichever is bigger. A scrollHeight above clientHeight means the content scrolls inside the box. thrown is every message the screen threw while it drew, word for word. While it draws, every run is refused — not while previewing — so a screenshot never writes to the base. theme picks light (the default) or dark. When it cannot be drawn the save still stands, and screenshot is {"unavailable": <reason>}.

Restore a widget

restore_widget Adds

Bring a trashed widget back.

Delete a widget

delete_widget Changes

Trash a widget. restore_widget brings it back. Refused while a board still draws it, naming the blocks. One with no source that nothing but your own open sitting ever touched is deleted outright instead, and has no way back.

Update a widget

update_widget Changes

Replace a widget's name, declaration, source or size — any of them in one save. Each is replaced whole, never merged.