Getting Started

Create your first reward-driven flag in minutes

Quick Start

Get up and running with Versia in three steps.

Versia is server-side only. Never call the API from browser JavaScript or mobile apps. API keys are bearer tokens; exposing them lets attackers exhaust your rate limit and break the integration for real users.

Step 1: Create a Flag and an Evaluation Key

Log into the Versia dashboard and create a new feature flag:

  1. Click “Create Flag”
  2. Give it a name (e.g., banner-cta)
  3. Add your variants (e.g., sign-up-free, start-trial, learn-more)
  4. Enable reward-driven mode
  5. Save

Then go to API Keys and generate an evaluation key. You’ll pass it as a bearer token from your server. (A separate agentic key is used by AI agents that manage flags via the agentic API - you don’t need it for runtime evaluation.)

Your flag is live. Traffic starts split equally across all variants.

Step 2: Connect Your App

Install the OpenFeature SDK for your language and point it at Versia. Pass your evaluation key as a bearer token, and use the Details variant of the call so you can read both the chosen variant key and the metadata Versia returns.

Go

provider := ofrep.NewProvider("https://api.versia.dev",
    ofrep.WithBearerToken("your-evaluation-key"))
openfeature.SetProvider(provider)

client := openfeature.NewClient("my-app")

evalContext := openfeature.NewEvaluationContext(
    "user-123",
    map[string]interface{}{
        "plan":   "pro",
        "device": "mobile",
    },
)
details, _ := client.StringValueDetails(ctx, "banner-cta", "sign-up-free", evalContext)
variant := details.Variant
// For reward-driven flags, capture the decision token (see Step 3).
token, _ := details.FlagMetadata["decision_token"].(string)

Node.js

OpenFeature.setProvider(new OFREPProvider({
  baseUrl: 'https://api.versia.dev',
  headers: { Authorization: 'Bearer your-evaluation-key' },
}));

const client = OpenFeature.getClient();
const ctx = { targetingKey: 'user-123', plan: 'pro', device: 'mobile' };
const details = await client.getStringDetails('banner-cta', 'sign-up-free', ctx);
const variant = details.value;
// For reward-driven flags, capture the decision token (see Step 3).
const decisionToken = details.flagMetadata?.decision_token;

Python

provider = OFREPProvider(
    "https://api.versia.dev",
    headers_factory=lambda: {"Authorization": "Bearer your-evaluation-key"},
)
api.set_provider(provider)
client = api.get_client()

context = EvaluationContext(
    targeting_key="user-123",
    attributes={"plan": "pro", "device": "mobile"},
)
details = client.get_string_details("banner-cta", "sign-up-free", context)
variant = details.variant
# For reward-driven flags, capture the decision token (see Step 3).
decision_token = (details.flag_metadata or {}).get("decision_token")

The context tells Versia who the user is. Attributes like plan and device power exclusion rules and help reward-driven flags personalize per segment. See Evaluation Context for details.

Step 3: Send Rewards

When a user takes the action you care about, send a reward. For reward-driven flags, echo the decisionToken you captured during evaluation - it links the reward back to the specific variant that user saw. Without it, the reward is silently dropped and Versia learns nothing.

// Pass the same context used during evaluation so Versia can personalize
const ctx = { targetingKey: 'user-123', plan: 'pro', device: 'mobile' };
client.track('conversion', ctx, { value: 1.0, decisionToken });
  • 1.0 = success (conversion, click, purchase)
  • No event = neutral (Versia handles this automatically)

The decision token is valid for 7 days, so place the reward at a point in your code that fires within that window of the evaluation. For longer attribution windows, see Reward-Driven Flags.

What Happens Next

Open the dashboard. Within a few hundred evaluations, you’ll see traffic shifting toward the better-performing variants. No analysis needed.

Next Steps

← IntroductionFlag Evaluation →