Skip to content
Blotout Docs

Update site settings

PATCH
/teams/{teamId}/domains/{domainId}/settings
curl --request PATCH \
  --url https://qinto-api.blotout.io/teams/7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9/domains/3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "tagGlobal": "acme", "fallbackCookie": "_shopify_y", "cookieSameSite": "strict", "consent": { "enabled": true }, "gpc": true, "autoCapture": { "pageLoad": false } }'

Changes any of the site’s snippet global, visitor-recovery cookie, first-party cookie mode, consent mode, Global Privacy Control handling and automatic capture in one call, which the site applies with a single redeploy.

How it works

Settings left out keep their value, and a value the site already has changes nothing. An invalid value stores nothing. A new tagGlobal is stored only once the site has redeployed: when the redeploy fails the call answers internal, the other settings in the call are stored and retry on their own, and repeating the call is safe. deployed is false until the site serves every stored setting: deploy a site that has never deployed; a deployed one retries on its own.

Required permissions

  • domain:write on 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”
teamId
required

Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.

string format: uuid

Example 

7b8d1a52-6c1e-4b6f-9a30-2f8a54d1c3e9

Unique id (UUID) of the team that owns the addressed resources, as shown in the team settings on the Blotout platform.

domainId
required

Unique id (UUID) of the site, as returned by the create and list operations.

string format: uuid

Example 

3f2a9c81-5d47-4e0b-8c66-91b2a7f04d15

Unique id (UUID) of the site, as returned by the create and list operations.

Request Bodyrequired

Section titled “Request Bodyrequired”

The settings to change.

Media typeapplication/json

Any of the site’s settings. Settings left out keep their current value.

object
tagGlobal

Window global for the snippet, at most 32 characters: a JavaScript identifier starting with a lowercase letter, _ or $. Null, blank or qinto restores the default.

string | null
<= 32 characters

Example 

acme
fallbackCookie

Name of the site’s own cookie to recover visitor ids from, at most 128 characters. Null or blank turns recovery off.

string | null
<= 128 characters

Example 

_shopify_y
cookieSameSite

SameSite mode of the first-party cookie Qinto recognizes returning visitors with. Allowed origins receive it only with none.

string
Allowed values: strict none

Example 

strict
consent

Consent mode.

object
enabled
required

Whether each event goes only to the apps whose consent category the visitor allowed. Off sends every event to every app.

boolean

Example 

true
gpc

Whether a visitor whose browser sends Global Privacy Control is treated as opted out of marketing and sale of data.

boolean

Example 

true
autoCapture

Events Qinto captures without the customer instrumenting them.

object
pageLoad
required

Whether Qinto records a page-load event without the customer instrumenting it.

boolean

Example 

false

Responses

Section titled “Responses”

200

Section titled “200”

The settings now stored, and whether the site already serves them.

Media typeapplication/json
object
settings
required

How a site’s snippet, cookies and privacy controls behave.

object
tagGlobal
required

Name of the window global the snippet binds, or null for the default qinto (window.qinto).

string | null
fallbackCookie
required

Name of the site’s own cookie Qinto reads to recover a visitor id after its own cookie expires, or null when recovery is off.

string | null
cookieSameSite
required

SameSite mode of the first-party cookie Qinto recognizes returning visitors with. Allowed origins receive it only with none.

string
Allowed values: strict none
consent
required

Consent mode.

object
enabled
required

Whether each event goes only to the apps whose consent category the visitor allowed. Off sends every event to every app.

boolean
gpc
required

Whether a visitor whose browser sends Global Privacy Control is treated as opted out of marketing and sale of data.

boolean
autoCapture
required

Events Qinto captures without the customer instrumenting them.

object
pageLoad
required

Whether Qinto records a page-load event without the customer instrumenting it.

boolean
deployed
required

Whether the site already serves every setting stored for it. False on a site that has never deployed — call deploy — and false while a change has not reached the site yet, which retries on its own.

boolean

Example 

{
  "settings": {
    "tagGlobal": "acme",
    "fallbackCookie": "_shopify_y",
    "cookieSameSite": "strict",
    "consent": {
      "enabled": true
    },
    "gpc": true,
    "autoCapture": {
      "pageLoad": false
    }
  },
  "deployed": true
}

400

Section titled “400”

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. invalid_settings — A window global or cookie name was rejected, and no setting was stored. message states which and why.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: invalid_params invalid_body invalid_settings
details

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
key
additional properties

Example 

{
  "error": "invalid_params",
  "details": {
    "errors": [],
    "properties": {
      "teamId": {
        "errors": [
          "Invalid UUID"
        ]
      }
    }
  }
}

401

Section titled “401”

unauthenticated — The Authorization: Bearer token is missing, malformed, or no longer valid. Generate a team API token or obtain a new OAuth access token.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: unauthenticated

Example 

{
  "error": "unauthenticated"
}

403

Section titled “403”

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.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: forbidden
message

Human-readable reason for this specific failure, intended for display — do not parse it programmatically.

string

Example 

{
  "error": "forbidden",
  "message": "The Cloudflare API token is invalid or expired."
}

404

Section titled “404”

not_found — The addressed resource does not exist within this team; check the id and retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: not_found

Example 

{
  "error": "not_found"
}

500

Section titled “500”

internal — Unexpected server error. Nothing is guaranteed to have been persisted; idempotent operations are safe to retry.

Media typeapplication/json
object
error
required

Machine-readable error slug; switch on this value rather than on the HTTP status alone.

string
Allowed values: internal

Example 

{
  "error": "internal"
}