Configure an app site install
const url = 'https://qinto-api.blotout.io/developer/organizations/9c1d2b34-5e67-4f89-a0b1-2c3d4e5f6a7b/apps/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d/sites/3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15/installs/8d7c6b5a-4938-4271-a605-9e8f7a6b5c4d/variables';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"values":{"BETA_CHECKOUT":true}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://qinto-api.blotout.io/developer/organizations/9c1d2b34-5e67-4f89-a0b1-2c3d4e5f6a7b/apps/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d/sites/3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15/installs/8d7c6b5a-4938-4271-a605-9e8f7a6b5c4d/variables \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "values": { "BETA_CHECKOUT": true } }'Stores values for the developer-owned variables of one installation on a site — a beta flag switched on for one customer, say. Only the names in the body are written; anything left out keeps its current value.
How it works
The response is the site’s resulting state, so no follow-up read is needed. A name the manifest gives to the site manager or to the app is refused with variable_invalid. A change reaches the site within about five minutes and lands in the site’s activity log with you as the actor; a call that changes nothing does neither.
Required permissions
- None beyond a valid token; requires an OAuth token with the
developerscope, for an owner of the addressed organization, or a member or developer of it with support access
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Unique id (UUID) of the organization that owns the addressed apps, as listed by GET /me under organizations.
Example
9c1d2b34-5e67-4f89-a0b1-2c3d4e5f6a7bUnique id (UUID) of the organization that owns the addressed apps, as listed by GET /me under organizations.
Unique id (UUID) of the app, as returned by the create and list operations.
Example
5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8dUnique id (UUID) of the app, as returned by the create and list operations.
Unique id (UUID) of the site, as returned by the list sites operation.
Example
3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15Unique id (UUID) of the site, as returned by the list sites operation.
Unique id (UUID) of the installation on that site, as returned by the get site operation.
Example
8d7c6b5a-4938-4271-a605-9e8f7a6b5c4dUnique id (UUID) of the installation on that site, as returned by the get site operation.
Request Bodyrequired
Section titled “Request Bodyrequired”The values to store, keyed by variable name.
object
The values to store, keyed by the variable name the manifest declares with owner: "developer". Omitted names keep their current value. A toggle takes a boolean; a select takes an option value or an empty string; a multiselect takes a list of option values or an empty list; the other types take a string.
object
The value to store: at most 5 KB of serialized JSON for a single-install app, 490 bytes for one that allows multiple installs.
Example
v2The value of a toggle variable.
Example
trueThe value of a multiselect variable: option values, stored in manifest order.
Example
[ "AddToCart", "Purchase"]Example
{ "BETA_CHECKOUT": true}Responses
Section titled “Responses”The site after the write.
object
A site running the app, its installations, and the developer-owned variables on each.
object
Server-assigned id of the app’s installation record on this site.
Id of the site. Address the site with it in the get site and configure install operations.
The site’s first-party hostname the app runs under.
The app version the site is on.
Whether the site manager has the app switched on.
When the site installed the app, as an ISO 8601 UTC timestamp.
The developer-owned variables the site’s version declares, in manifest order. Empty when it declares none.
One per-install setting the app’s manifest hands to the developer (owner: "developer"). A site manager never sees it; the developer sets it per install.
object
Name the app’s manifest declares the variable under, and the name to send when setting its value.
Where the value is stored: a plain value is readable back, a secret one is write-only and never returned.
How a form should render the input. A toggle takes a boolean value; a select takes the value of one of options, or an empty string for none; a multiselect takes a list of options values, empty for none; the others take a string.
Display label the manifest gives the variable.
Whether the value also ships into the site’s browser bundle.
One-line guidance the manifest supplies, or null when it supplies none.
Link to further documentation, or null when the manifest supplies none.
The choices of a select or multiselect, in manifest order, or null for every other type.
One choice of a select or multiselect variable.
object
The value to send and the value stored when this option is picked.
The text a form shows for this option.
Whether a form pre-selects this option while the install has no value. The platform never stores a default on its own.
The live installations on the site, in ordinal order.
One installation of the app on a site, with the developer-owned state of its variables.
object
Id of the installation. Address it with the configure install operation.
Position of the installation on the site, from 1.
The label the site manager gave the installation.
Whether the site manager has this installation switched on.
The stored values of the developer-owned plain variables, keyed by name. A name with no value is absent.
object
The value of a text, password or select variable.
The value of a toggle variable.
The value of a multiselect variable: option values in manifest order.
The developer-owned secret variables that hold a value. Values are never returned.
Example
{ "site": { "domainAppId": "7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9", "domainId": "3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15", "domain": "q.shop.example.com", "version": "1.4.1", "enabled": true, "installedAt": "2026-08-17T12:00:00.000Z", "variables": [ { "name": "BETA_CHECKOUT", "kind": "plain", "type": "text", "label": "Beta checkout", "browser": false, "helpText": "Turns on the redesigned checkout for this site.", "helpUrl": "https://developers.example.com/beta-checkout", "options": null } ], "installs": [ { "appInstallId": "8d7c6b5a-4938-4271-a605-9e8f7a6b5c4d", "ordinal": 1, "label": "EU pixel", "enabled": true, "variables": { "BETA_CHECKOUT": true }, "secretsSet": [ "BETA_KEY" ] } ] }}invalid_params — A path parameter failed validation (for example a malformed UUID); details pinpoints the offending parameter. invalid_body — The JSON body is unparseable or failed schema validation; details pinpoints the offending fields when the body could be parsed.
object
Machine-readable error slug; switch on this value rather than on the HTTP status alone.
Field-level validation errors: a tree keyed by input property, each node carrying an errors array of human-readable messages. Render it to help the caller correct the request.
object
Example
{ "error": "invalid_params", "details": { "errors": [], "properties": { "teamId": { "errors": [ "Invalid UUID" ] } } }}unauthenticated — The Authorization: Bearer token is missing, malformed, or no longer valid. Generate a team API token or obtain a new OAuth access token.
object
Machine-readable error slug; switch on this value rather than on the HTTP status alone.
Example
{ "error": "unauthenticated"}forbidden — The bearer credential lacks the required permission or belongs to another team, or its user lacks the organization role a developer operation needs. Update its policies, use a credential bound to the addressed team, or ask an organization owner for the role; message states the reason when one is known.
object
Machine-readable error slug; switch on this value rather than on the HTTP status alone.
Human-readable reason for this specific failure, intended for display — do not parse it programmatically.
Example
{ "error": "forbidden", "message": "The Cloudflare API token is invalid or expired."}not_found — The addressed resource does not exist within this team; check the id and retry.
object
Machine-readable error slug; switch on this value rather than on the HTTP status alone.
Example
{ "error": "not_found"}variable_invalid — The app declares no variable by that name, or another party sets the name (the site manager, the app developer, or the app’s own panel); message names it. variable_too_large — A value exceeds its serialized limit: 256 KB for a large variable, 5 KB for another variable of a single-install app, 490 bytes for one of an app that allows multiple installs or for an app-scope variable; message names the variable, its size and the limit. variable_budget — One variable’s values across every install of the app on this site exceed 5 KB together, or all large values of the app’s worker exceed 1 MB, removed installs included until they are purged; message states the size. Shorten a value before retrying; a removed install frees its share once it is purged.
object
Machine-readable error slug; switch on this value rather than on the HTTP status alone.
Human-readable reason for this specific failure, intended for display — do not parse it programmatically.
Example
{ "error": "variable_invalid", "message": "The Cloudflare API token is invalid or expired."}internal — Unexpected server error. Nothing is guaranteed to have been persisted; idempotent operations are safe to retry.
object
Machine-readable error slug; switch on this value rather than on the HTTP status alone.
Example
{ "error": "internal"}