Update an app install
const url = 'https://qinto-api.blotout.io/teams/7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9/domains/3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15/apps/facebook-capi/installs/8d7c6b5a-4938-4271-a605-9e8f7a6b5c4d';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"label":"EU pixel"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://qinto-api.blotout.io/teams/7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9/domains/3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15/apps/facebook-capi/installs/8d7c6b5a-4938-4271-a605-9e8f7a6b5c4d \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "label": "EU pixel" }'Renames an install with { label }, flips its own switch with { enabled }, or sets where it runs with { geoFilter }; geoFilter: null removes the geo filter. Send one of the three per call. The app-level kill switch is a different operation.
How it works
A call that repeats the stored value succeeds and changes nothing. Disabling one install leaves the others running. Geo filter lists are stored deduplicated and sorted. An unknown location, the same location in both lists, or a US state next to US in one list is refused as invalid_body, and details names the entry. An OAuth token’s user also needs an app role of admin or higher on the site.
Required permissions
domain:manage_domain_apps:writeon all domains, or on the addressed domain when its id is in the route
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.
Example
7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.
Unique id (UUID) of the site, as returned by the site operations.
Example
3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15Unique id (UUID) of the site, as returned by the site operations.
Immutable slug of the app, as shown by the list operation.
Example
facebook-capiImmutable slug of the app, as shown by the list operation.
Unique id (UUID) of the installation, as returned by the installs operation.
Example
8d7c6b5a-4938-4271-a605-9e8f7a6b5c4dUnique id (UUID) of the installation, as returned by the installs operation.
Request Bodyrequired
Section titled “Request Bodyrequired”The replacement label, the install-level switch, or the geo filter.
object
The replacement label.
Example
EU pixelobject
The replacement install-level switch state.
Example
falseobject
Where the install runs for visitors’ browser sessions. Each entry is an ISO 3166-1 alpha-2 country code (SI), EU for the European Union, or an ISO 3166-2 code for one of the 50 US states or the District of Columbia (US-CA). The install runs only when the visitor’s location is known, the include list is empty or one of its entries matches, and no exclude entry matches. A country code matches that country, EU matches a country in the European Union, and a state code matches a US visitor in that state. The location is unknown, and the install does not run, when the visitor’s country is not reported, when a list names a US state and a US visitor’s state is not reported, or when a list holds EU and the visitor’s location carries no EU flag. Server SDK events, schedules, webhooks, app endpoints, MCP tools and calls from other apps are not filtered.
object
Locations the install runs in; empty means every location the exclude list allows.
Example
[ "EU"]Locations the install never runs in.
Example
[ "US-CA"]Responses
Section titled “Responses”Whether the label, switch or geo filter actually changed.
object
Whether the switch actually changed.
Example
{ "updated": true}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. registry_budget — The change would grow the site’s app configuration past the size the site worker can deploy. Remove an app or an install, or shorten install labels and geo filters, then retry. message states the refusal. app_suspended — Blotout has suspended this app, so nothing ran and nothing changed. The call works again once the suspension is lifted.
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"}