What it does
Create or replace a value by key. site_id on create puts it on that site; without it an account key puts it on the account, which every site reads, and a site key on its own site. move_value moves it later. read_access: public = pages, page scripts (bp.value) and GET /data/_values can read it. private (default) = pages can print it ({{ values.key }}) when the site owns it or has a share, but scripts and the public JSON can't. secret = for tokens, API keys and passwords: stored encrypted, never on a page, in a script, in the public JSON or in a site template; a page that uses it is refused at save; only get_value returns the content, and list_values shows the key only. template_safe defaults to false; only a template-safe value is copied into a site template, and a secret value can't be template-safe. The response hides a secret's content.
Plans
Works on every plan: Free, Basic, Pro and Ultra.
Parameters
| Name | Type | About |
|---|---|---|
keyrequired | string | The value's key. Pages read it as {{ values.key }}. |
type | string | The value's type: text, number, date, money or percentage. |
valuerequired | string or number | A string for text and date values, a JSON number for number, money and percentage values. |
format | object | How a number shows: currency, decimals, unit and compact. |
read_access | one of: public, private, secret | public: pages, scripts and the public JSON can read it. private (default): only pages can print it. secret: for tokens and keys, never shown anywhere. |
template_safe | boolean | true lets the value be copied into a site template. Default false; a secret can't be template-safe. |
site_id | string | The id of the site. list_sites gives the ids of your sites. |
Example
Call upsert_value with these arguments:
{
"key": "opening_hours",
"type": "text",
"value": "Mon–Fri 9:00–17:00",
"read_access": "public",
"site_id": "01a1…"
}
Ids like 01a1… stand for your own. list_sites and list_tables give you the real ones.
Related guides
- ValuesSingle facts, such as a total, a status or a token.