State & Variables

1. Overview

State is the hierarchical data tree available to ResultFly campaigns, composed of declared business variables plus system-managed fields. This reference describes the APIs for defining variables and interacting with State at runtime. For concepts, see Overview → State in ResultFly and Developers → State Model in ResultFly.

2. Authentication

• Variable definition endpoints require admin or server-to-server credentials. Follow Integration Basics → Authentication for key provisioning.
• Runtime state endpoints use user-context JWTs (client-managed or ResultFly-managed). See Integration Basics → User Tokens for issuance details.

3. Endpoints

3.1 POST /v1/campaigns/{campaign_id}/variables:define

Declare a variable for a campaign.

Request body

Behavior

• Variable becomes available under state.{scope}.{name} once defined.
• If the scope already has the maximum allowed variables, ResultFly returns a configuration error.

Response example

{
  "status": "defined",
  "variable": {
    "scope": "user",
    "name": "loyalty_points",
    "type": "number",
    "default": 0
  }
}

3.2 GET /v1/campaigns/{campaign_id}/variables

List declared variables for a campaign (all scopes).

Response example

{
  "variables": [
    { "scope": "user", "name": "loyalty_points", "type": "number", "default": 0 },
    { "scope": "campaign", "name": "tier", "type": "string", "default": "bronze" },
    { "scope": "app", "name": "round_score", "type": "number" }
  ]
}

3.3 GET /v1/runtime/state

Return the current values of declared variables for the authenticated user context.

Response example

{
  "state": {
    "user": {
      "loyalty_points": 1200,
      "daily_attempts": 1
    },
    "campaign": {
      "tier": "silver"
    },
    "app": {
      "round_score": 35
    }
  }
}

System fields (such as sessionId) are excluded from this endpoint.

3.4 POST /v1/runtime/state:mutate

Mutate declared variables for the authenticated user context.

Request body

Behavior

• Each operation must target a declared variable; referencing state.sessionId or any system field results in an error.
• set assigns the provided value, inc/dec adjust numeric values.
• If mutation_id repeats, ResultFly returns the original outcome without reapplying changes.

Response example

{
  "status": "applied",
  "mutations": [
    { "path": "state.user.loyalty_points", "previous": 1200, "current": 1250 },
    { "path": "state.app.round_score", "previous": 35, "current": 0 }
  ]
}

4. Error Handling

• Validation errors — missing fields, type mismatches, or invalid scopes. These return 422 Unprocessable Entity with details.
• Scope errors — attempting to exceed per-scope variable limits or mutate a variable outside the authenticated campaign/app context results in 403 Forbidden or 409 Conflict depending on policy.
• Idempotency behavior — when mutation_id repeats, the API returns the original response (status duplicate) without reapplying changes.
• System State violations — writing to system fields or undeclared variables returns 400 Bad Request with the offending path; callers must fix configuration before retrying.