Reference
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.
This page covers the public evaluation API only. To create and update flags, targets, and targeting rules, or read the audit trail programmatically, see the Management API reference.
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-ZEN-API-KEY. The legacy X-API-KEY and X-ZENMANAGE-KEY headers are also still accepted as aliases.
GET /v1/flags and GET /v1/flags/{flag-key} require a server key — a mobile or client key returns a 401. POST /v1/flags/{flag-key}/usage and GET /v1/flag-json accept any key type, and the key you send determines the platform payload returned.
GET /v1/flags HTTP/1.1
Host: api.zenmanage.com
Content-Type: application/json
X-ZEN-API-KEY: tok_your_server_key_hereRate limits and error posture
The public limit is 100 requests per minute, applied per client IP address. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining headers; exceeding the limit returns a 429 with a Retry-After header. 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-ZEN-CONTEXT. The legacy X-ZENMANAGE-CONTEXT header (or the shortened C alias) is also still accepted.
A context includes a required type, a stable identifier, an optional name, and an optional array of attributes.
X-ZEN-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-ZEN-DEFAULT-VALUE header. The legacy X-DEFAULT-VALUE header (or the shortened D alias) is also still accepted.
X-ZEN-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 public API at https://api.zenmanage.com/v1/api-docs. Use it for client generation, schema validation, and endpoint exploration. This page mirrors that spec — if the two ever disagree, treat the spec as authoritative.
Endpoints
Evaluates every flag in the environment against the supplied context and returns the resolved values.
{
"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" }
}
}
]
}Evaluates one flag by key. Use this path when you only need a single value and want smaller response bodies.
{
"status": "success",
"data": {
"flag": {
"key": "new-checkout",
"name": "New Checkout",
"type": "boolean",
"value": { "boolean": false }
}
}
}Records that a flag was used. SDKs can do this for you automatically when usage reporting is enabled.
{
"status": "success"
}Returns the location of a precomputed, per-platform flag JSON blob for the resolved environment instead of evaluating flags synchronously. Requires the X-ZEN-CLIENT-AGENT header, formatted as <sdk-family>/<version> (for example zenmanage-javascript/1.2.0). The SDK family in that header must match the type of key you send — a client-key request from a server SDK family is rejected. This endpoint does not accept X-ZEN-DEFAULT-VALUE (or its legacy aliases).
{
"status": "success",
"data": {
"url": "https://cdn.zenmanage.com/flags/env_.../server.json",
"cdn": "https://cdn.zenmanage.com",
"path": "/flags/env_.../server.json",
"signed": false
}
}Common errors
400 Bad Request: the context header is present but cannot be decoded.
401 Unauthorized: the server/mobile/client key is missing, invalid, or of the wrong type for the endpoint.
403 Forbidden: on GET /v1/flag-json only — the X-ZEN-CLIENT-AGENT header is missing or its SDK family isn't recognized.
404 Not Found: the requested flag key does not exist in the selected environment.
429 Too Many Requests: the rate limit was exceeded — back off using the Retry-After header.
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.