API Reference

Authenticate with server, mobile, or client keys, send context when you need targeting, and use safe defaults so your application keeps working during failures.

Overview

Zenmanage exposes a JSON-based API at https://api.zenmanage.com for retrieving evaluated flags and reporting usage. The API is environment-scoped, and each request key maps to a platform payload type.

Use a server key for backend runtimes, a mobile key for mobile SDK delivery, or a client key for browser/client SDK delivery. The key you send determines which filtered payload is returned.

Use the API directly when you want precise control over requests or when your runtime does not use one of the current SDKs. If you do use an SDK, this page still defines the headers and response shapes those SDKs build around.

Prerequisites

A server, mobile, or client key copied from the Zenmanage admin app for the exact environment you want to evaluate.
A stable context identifier if your rollout depends on targeting rules or percentage rollouts.
A default value strategy for every flag your application reads.

Authentication

Send your server, mobile, or client key with every request. The canonical header is X-API-KEY. If your platform reserves that name, use X-ZENMANAGE-KEY instead.

Platform key headerhttp

GET /v1/flags HTTP/1.1
Host: api.zenmanage.com
Content-Type: application/json
X-API-KEY: tok_your_server_key_here

Rate limits and error posture

The public limit documented today is 60 requests per minute per application. If your integration needs a higher rate, contact hello@zenmanage.com before you scale up traffic.

The common failure cases to handle are invalid platform keys, malformed context headers, and flag lookups for unknown keys. Safe defaults in your application are the simplest mitigation.

Context header

Contexts let Zenmanage evaluate rules against the actor making the request. A context can describe a user, organization, service, or any other entity you model in your application. Send it through X-ZENMANAGE-CONTEXT. If needed, the short alias C is also supported.

A context includes a required type, a stable identifier, an optional name, and an optional array of attributes.

Context header examplejson

X-ZENMANAGE-CONTEXT: {
  "type": "user",
  "name": "Jane Doe",
  "identifier": "usr_01hzy9m2qj1q1jz3sd4xg9n1vb",
  "attributes": [
    {
      "key": "country",
      "values": [{ "value": "US" }]
    },
    {
      "key": "plan",
      "values": [{ "value": "enterprise" }]
    }
  ]
}

See Contexts and Attributes for a deeper explanation of how to model identifiers and attributes.

Default values

Default values tell Zenmanage what your application will serve if a flag is unavailable. They are optional, but strongly recommended because they make fallback behavior explicit and help surface missing-default-value reports.

Send the JSON payload in the X-DEFAULT-VALUE header.

Default values headerjson

X-DEFAULT-VALUE: [
  { "key": "new-checkout", "type": "boolean", "value": false },
  { "key": "welcome-theme", "type": "string", "value": "classic" },
  { "key": "max-items", "type": "number", "value": 100 }
]

OpenAPI specification

Zenmanage publishes an OpenAPI v3 document for the API at https://api.zenmanage.com/v1/api-docs. Use it for client generation, schema validation, and endpoint exploration.

Endpoints

GET https://api.zenmanage.com/v1/flags

Evaluates every flag in the environment against the supplied context and returns the resolved values.

All flags responsejson

{
  "status": "success",
  "data": [
    {
      "flag": {
        "key": "new-checkout",
        "name": "New Checkout",
        "type": "boolean",
        "value": { "boolean": false }
      }
    },
    {
      "flag": {
        "key": "landing-page-variant",
        "name": "Landing Page Variant",
        "type": "string",
        "value": { "string": "control" }
      }
    }
  ]
}

GET https://api.zenmanage.com/v1/flags/{flag-key}

Evaluates one flag by key. Use this path when you only need a single value and want smaller response bodies.

Single flag responsejson

{
  "status": "success",
  "data": {
    "flag": {
      "key": "new-checkout",
      "name": "New Checkout",
      "type": "boolean",
      "value": { "boolean": false }
    }
  }
}

POST https://api.zenmanage.com/v1/flags/{flag-key}/usage

Records that a flag was used. SDKs can do this for you automatically when usage reporting is enabled.

Usage responsejson

{
  "status": "success"
}

Common errors

400 Bad Request: the context header is present but cannot be decoded.

401 Unauthorized: the server/mobile/client key is missing or invalid.

404 Not Found: the requested flag key does not exist in the selected environment.

Next step

Take the next integration step in your own stack.

Start with the quickstart that matches your runtime, then return to the reference pages when you need exact request and payload details.

View quickstarts Start free trial