Skip to content
Blotout Docs

Set app variables

PATCH
/developer/organizations/{organizationId}/apps/{appId}/variables
curl --request PATCH \
  --url https://qinto-api.blotout.io/developer/organizations/9c1d2b34-5e67-4f89-a0b1-2c3d4e5f6a7b/apps/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d/variables \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "values": { "API_BASE": "https://api.example.com" } }'

Stores values for the app’s app-scope variables. The body is a partial merge: names it omits keep their current value, and a value cannot be cleared once set.

How it works

The response is the resulting state of every variable, so no follow-up read is needed. A change reaches a running app within about five minutes; an app that needs to read a value back immediately should keep that state in its own storage instead.

Required permissions

  • None beyond a valid token; requires an OAuth token with the developer scope, for an owner or developer of the addressed organization

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organizationId
required

Unique id (UUID) of the organization that owns the addressed apps, as listed by GET /me under organizations.

string format: uuid

Example 

9c1d2b34-5e67-4f89-a0b1-2c3d4e5f6a7b

Unique id (UUID) of the organization that owns the addressed apps, as listed by GET /me under organizations.

appId
required

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

string format: uuid

Example 

5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d

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

Request Bodyrequired

Section titled “Request Bodyrequired”

The values to store, keyed by variable name.

Media typeapplication/json
object
values
required

The values to store, keyed by the variable name the manifest declares. Omitted names keep their current value, and there is no way to clear one. Every name must be declared by some version of the app.

object
key
additional properties

The value to store, 1-490 bytes.

string
>= 1 characters <= 490 characters

Example 

https://api.example.com

Example 

{
  "API_BASE": "https://api.example.com"
}

Responses

Section titled “Responses”

200

Section titled “200”

The app’s app-scope variables after the write.

Media typeapplication/json
object
variables
required

Every app-scope variable any version of the app declares, in the order the earliest version that declares each one lists it. Empty when no version declares any.

Array<object>

One app-scope setting: a value the developer sets once for the app, delivered identically to every site that installs it. Distinct from a site app’s per-install variables, which a site manager fills in.

object
name
required

Name the app’s manifest declares the variable under, and the name to send when setting its value.

string
kind
required

Where the value is stored: a plain value is readable back, a secret one is write-only and never returned.

string
Allowed values: plain secret
type
required

How a form should render the input for this variable.

string
Allowed values: text password
label
required

Display label the manifest gives the variable.

string
required
required

Whether a version that declares this variable refuses to publish until it has a value.

boolean
helpText
required

One-line guidance the manifest supplies, or null when it supplies none.

string | null
helpUrl
required

Link to the vendor’s own documentation for this value, or null when the manifest supplies none.

string | null
value
required

The stored value for a plain variable, or null when it has none. Always null for a secret variable.

string | null
set
required

Whether a value is stored for this variable.

boolean

Example 

{
  "variables": [
    {
      "name": "META_APP_SECRET",
      "kind": "plain",
      "type": "text",
      "label": "Meta app secret",
      "required": true,
      "helpText": "Found under App settings in the Meta developer console.",
      "helpUrl": "https://developers.example.com/app-secret",
      "value": "https://api.example.com",
      "set": 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.

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
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"
}

409

Section titled “409”

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.

Media typeapplication/json
object
error
required

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

string
Allowed values: variable_invalid variable_too_large
message

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

string

Example 

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

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"
}