Skip to main content

Documentation Index

Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt

Use this file to discover all available pages before exploring further.

Resolving flags means getting the value of a flag for a given evaluation context. The evaluation context contains information about the user, device, or other contextual data that Confidence uses to determine which variant to return.

​
Before You Begin

Before resolving flags, you need:
  1. A flag client with credentials
  2. Flags associated with the client
  3. Rules defined on your flags
While you can resolve flags directly using the API as shown here, the most efficient way is using one of the Confidence SDKs. The SDKs handle caching, batching, and other optimizations automatically.

​
Authentication

Resolve operations use client secrets for authentication, not Bearer tokens: 
curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": { ... }
  }'

​
Evaluation Context

The evaluation context specifies contextual data that Confidence uses to evaluate rules. It’s a schema-less key-value map (JSON object) containing any data needed for rule evaluation, such as:
  • User identifiers
  • User attributes (country, age, plan level)
  • Device information (OS, model, browser)
  • Session data (URL, referrer, timestamp)
Example evaluation context: 
{
  "user_id": "rosling",
  "country": "SE",
  "device": {
    "vendor": "apple",
    "os": "ios"
  }
}
Do not pass sensitive data in the keys of the evaluation context. Values are never stored, but keys are temporarily stored to help derive the schema for targeting.
The recommended approach is to batch resolve all flags for a client. This returns values for all flags associated with the client: 
curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": {
      "user_id": "rosling",
      "country": "SE",
      "device": {
        "vendor": "apple",
        "os": "ios"
      }
    }
  }'
Response: 
{
  "resolvedFlags": [
    {
      "flag": "flags/button-colors",
      "variant": "",
      "value": {},
      "flagSchema": {
        "schema": {}
      },
      "reason": "RESOLVE_REASON_NO_SEGMENT_MATCH"
    },
    {
      "flag": "flags/image-size",
      "variant": "flags/image-size/variants/control",
      "value": {
        "name": "costello",
        "img-size": 42
      },
      "flagSchema": {
        "schema": {
          "name": {
            "stringSchema": {}
          },
          "img-size": {
            "intSchema": {}
          }
        }
      },
      "reason": "RESOLVE_REASON_MATCH"
    }
  ],
  "resolveToken": "<resolve token>"
}
Keep the resolveToken from the response. You’ll need it when applying flags to track usage.

​
Resolve Specific Flags

You can limit the resolve operation to specific flags using the flags parameter: 
curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "flags": ["flags/image-size", "flags/button-colors"],
    "evaluationContext": {
      "user_id": "rosling",
      "country": "SE"
    }
  }'
This returns only the specified flags, which can reduce response size and processing time.

​
Understand Resolve Reasons

Each resolved flag includes a reason field explaining why it resolved the way it did:
ReasonDescription
RESOLVE_REASON_MATCHA rule matched and assigned a variant
RESOLVE_REASON_NO_SEGMENT_MATCHNo rule matched the evaluation context
RESOLVE_REASON_FLAG_ARCHIVEDThe flag is archived
RESOLVE_REASON_ERRORAn error occurred during resolution

​
Test Resolve Logic

To test your resolve logic with different evaluation contexts:
  1. Vary the context: Try different user IDs, countries, device types
  2. Check reasons: Look at the reason field to understand why each flag resolved as it did
  3. Verify variants: Ensure the returned variants match your expectations
  4. Test edge cases: Try missing fields, null values, unexpected data types
Example testing different contexts: 
# Test user from Sweden
curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": {
      "user_id": "user123",
      "country": "SE"
    }
  }'

# Test user from US
curl -X POST "https://flags.confidence.dev/v1/flags:resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "clientSecret": "YOUR_CLIENT_SECRET",
    "evaluationContext": {
      "user_id": "user456",
      "country": "US"
    }
  }'

​
Handle No Match

When no rule matches, the flag returns with RESOLVE_REASON_NO_SEGMENT_MATCH and empty values: 
{
  "flag": "flags/my-flag",
  "variant": "",
  "value": {},
  "reason": "RESOLVE_REASON_NO_SEGMENT_MATCH"
}
Your application should handle this case by:
  • Using a default value specified in your code
  • Falling back to the original behavior
  • Logging the no-match event for debugging

​
Best Practices

  1. Batch resolve: Always resolve all flags in one call to minimize network overhead
  2. Cache locally: Cache resolved values to avoid repeated API calls
  3. Provide complete context: Include all relevant fields that your targeting rules might use
  4. Handle failures gracefully: Have fallback values if the resolve call fails
  5. Use consistent keys: Ensure the targeting_key (or custom field) is stable for each user

​
Next Steps

After resolving flags:
  1. Use the variant values in your application
  2. Apply the flags to track usage and enable experiment analysis
  3. Monitor resolve patterns and optimize your rules as needed