HTTP & REST API

Authentication

Every integration request to /api/flags* or /flags/* must include an x-management-key header. The key carries its own org and permission scope.

x-management-key: YOUR-MANAGEMENT-KEY

Key lifecycle

A key is 64 lowercase hex characters. The plaintext is returned once — in the create response and again on rotate — and is never retrievable afterwards, so store it in your secret manager immediately. The list view shows only the first 8 characters so you can tell keys apart. Only admin and globaladmin can create, rotate, disable, or delete keys.

Endpoints

Creates a new flag in the org owning the key. Returns 409 if a flag with the same name already exists.

Request headers

x-management-key: <your-key>
Content-Type: application/json

Request body fields

{
  "name": "checkout-redesign",
  "project": "Main App",
  "type": "release",
  "description": "Q3 checkout flow rewrite",
  "tags": ["checkout", "q3"],
  "variants": [
    { "key": "on",  "value": true,  "valueType": "boolean" },
    { "key": "off", "value": false, "valueType": "boolean" }
  ],
  "dependsOn": []
}

Curl

curl -X POST $HOST/api/flags \
  -H "x-management-key: $FF_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  --data @create-flag.json

Response (201 Created)

{
  "name": "checkout-redesign",
  "type": "release",
  "project": "Main App",
  "owner": "api",
  "description": "Q3 checkout flow rewrite",
  "tags": ["checkout", "q3"],
  "variants": [{ "key": "on", "value": true, "valueType": "boolean" }, { "key": "off", "value": false, "valueType": "boolean" }],
  "dependsOn": [],
  "isArchived": false,
  "activatesAt": null,
  "expiresAt": null,
  "createdAt": "2026-05-17T18:30:00Z"
}

Returns flag definitions newest first. An application-scoped key only receives flags in that application.

Curl

curl $HOST/api/flags \
  -H "x-management-key: $FF_MANAGEMENT_KEY"

Returns one flag definition or 404. It does not embed per-stage configs. An out-of-scope flag returns 403.

Partial update — every body field is optional, only the fields you send are changed. Variants, archive state, tags, dependencies, owner, project, description are all updatable here. Per-stage toggle/rollout/rules are on the configs endpoint below.

{
  "description": "Approved by Eng leadership",
  "tags": ["checkout", "q3", "approved"]
}

{ "isArchived": true }

Curl

curl -X PUT $HOST/api/flags/checkout-redesign \
  -H "x-management-key: $FF_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  --data @update-flag.json

Permanently removes the flag and every per-stage config row that references it in one transaction. Cache is purged immediately. Subsequent eval requests for this flag return 404.

Curl

curl -X DELETE $HOST/api/flags/checkout-redesign \
  -H "x-management-key: $FF_MANAGEMENT_KEY"

Creates or updates the per-stage configuration for one (flag, stage) pair. This is what you call to enable / disable a flag in a specific environment, set its rollout percentage, or install targeting rules. Only the cache entry for that exact (flag, stage) is invalidated — other envs keep their warm cache.

If a running automation plan still controls that environment, writing its configuration here — or through the enabled and DELETE config endpoints — suspends the plan in the same save, so its next step can't overwrite your change. The plan's reason says a Management API key made the change; resume it from the flag's Automation tab.

Request body fields

{
  "stage": "production",
  "enabled": true,
  "defaultVariantKey": "off",
  "rolloutPercentage": 25,
  "rules": []
}

{
  "stage": "production",
  "enabled": true,
  "defaultVariantKey": "off",
  "rolloutPercentage": 100,
  "rules": [
    {
      "id": "pro-users",
      "priority": 10,
      "conditions": [
        { "field": "plan", "operator": "==", "value": "pro" }
      ],
      "allocations": [
        { "variantKey": "on", "percentage": 100 }
      ]
    }
  ]
}

Curl

curl -X POST $HOST/api/flags/checkout-redesign/configs \
  -H "x-management-key: $FF_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  --data @config.json

Response (200 OK)

{
  "id": "0d5b9b04-9b6e-4d1d-bc11-a3a73e6e0001",
  "flagId": "checkout-redesign",
  "stage": "production",
  "clientId": null,
  "enabled": true,
  "defaultVariantKey": "off",
  "rolloutPercentage": 25,
  "rules": []
}

Querying flag values (Evaluation API)

The hot read path is served by the Management API on the same host as the rest of the platform, under POST /flags/{key}. It uses its own per-key rate-limit policy so evaluation traffic stays isolated from flag reads and writes. It authenticates through the same x-management-key header used by the rest of this page. Create the key under Management Keys with CanEvaluate permission and an application scope; environment scope is optional.

Curl

curl -X POST "$HOST/flags/checkout-redesign?explain=true" \
  -H "x-management-key: $FF_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-42",
    "stage": "production",
    "context": { "plan": "pro", "country": "DE" }
  }'

Response

{
  "variant": true,
  "key": "on",
  "reason": {
    "code": "rule_matched",
    "message": "Matched rule 'pro-users' (priority 10). Variant chosen by allocation.",
    "ruleId": "pro-users"
  }
}

Calling it from your language

The same requests documented above, written with each language's own HTTP client — no dependency to add. Swap in your host, Management Key, flag name, and stage. If you are on .NET, prefer the official SDK package over hand-rolled HTTP.

// No install needed — Node 18+ ships a built-in fetch

const BASE_URL = 'https://maxlona.com';
const MANAGEMENT_KEY = 'YOUR_MANAGEMENT_KEY';
const STAGE = 'production';

async function evaluateFlag(flagKey, userId, context = {}) {
  const response = await fetch(BASE_URL + '/flags/' + flagKey, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-management-key': MANAGEMENT_KEY
    },
    body: JSON.stringify({
      userId, stage: STAGE, clientId: '', context
    })
  });

  if (!response.ok) throw new Error('Evaluation failed: ' + response.status);
  return await response.json(); // { key: "control", variant: ... }
}

function isEnabled(result) {
  return result.key !== 'off' && result.key !== '';
}

// Usage
async function main() {
  const context = { lenderId: '100' };

  const result = await evaluateFlag('my-feature-flag', 'user-123', context);
  console.log('Enabled:', isEnabled(result));
  console.log('Key:', result.key);         // "control", "treatment", etc.
  console.log('Variant:', result.variant); // true, "classic", 42, "#3b82f6"
}

main().catch(console.error);

Error responses