What it does
Define a visitor action on one table this site owns. kind toggle flips a checkbox. kind set writes a text or select column to one of at least two allowed values, and when can set other columns from the chosen value ($today, $now, null, or a literal). kind fixed writes constant values, or a bounded integer param that sets a date to $today plus that many days. kind edit lets the visitor write the columns in fields (each a column key, or { column, max_length, min, max, required }); set adds fixed writes. kind add creates a row from fields plus set; every required column must be in one of them. kind delete removes the row. edit, add and delete are only off, owner, share, member_own, or member_all, never public. A relation column can be an edit or add field (the visitor sends a row id) or a fixed row id in set or when, only with access off, owner, member_own or member_all; the related table must be one this site reads, and a call checks that the caller may read the linked row. access defaults to off. public needs can_public_actions. member_own lets members of the site with role edit add rows, which then belong to them, and change or delete only their own rows; member_all lets them change any row. An owner visit passes both. An account key may name an account-owned table no other site uses; it then moves to this site, so the action can come before the page. A site key cannot take account tables. Other sites' tables and shared tables are refused.
Plans
Works on every plan: Free, Basic, Pro and Ultra.
Parameters
| Name | Type | About |
|---|---|---|
site_idrequired | string | The id of the site. list_sites gives the ids of your sites. |
namerequired | string | The action's name. Pages run it by this name. |
tablerequired | string | The table the action changes. |
kindrequired | one of: toggle, set, fixed, edit, add, delete | toggle flips a checkbox; set picks one allowed value; fixed writes set values; edit, add and delete change, create or remove a row. |
access | one of: off, owner, share, share_review, public, member_own, member_all | Who may run it: off (default), owner, share, share_review, public, member_own or member_all. edit, add and delete are never public. |
column | string or null | The column a toggle or set action writes. |
allowed | array of string | For set: the values a visitor may choose, at least two. |
when | object | For set: other columns to write for each chosen value, such as a done date. |
set | object | Fixed column values written every time the action runs. |
params | array of objects | For fixed: a bounded number a visitor chooses, such as days from today, each with name, min, max and column. |
fields | array of string or object | For edit and add: the columns a visitor may write, each a column key or an object with limits. |
idempotency_key | string | Any unique string (1-200 printable ASCII). A retry with the same key and arguments returns the first call's result instead of running again. Same as the Idempotency-Key header. |
Example
Call define_action with these arguments:
{
"site_id": "01a1…",
"name": "toggle_done",
"table": "tasks",
"kind": "toggle",
"column": "done",
"access": "public"
}
Ids like 01a1… stand for your own. list_sites and list_tables give you the real ones.
Related guides
- What visitor actions areNamed, limited changes people make from a page.
- Tick, edit, add and deleteThe kinds of action, and when to use each.