Admin API

Introduction

The Admin API is the HTTPS interface to everything you manage in the dashboard for a project: projects, environments, configs and their targeting rules, segments, and tags. The Terraform provider and the MCP server are built on it, and anything they can do, a script of yours can do too.

Every request goes through the same validations as the dashboard, so a value that the dashboard would refuse is refused here with the same message. Every change shows in the audit log with a source of API and the name of the token that made it.

The API describes itself with an OpenAPI 3.1 document, which needs no authentication:

https://api.configdirector.com/v1/openapi.json

It holds the exact request and response schema of every endpoint on this page, including the targeting rule and segment condition shapes, and the base URL below as its server, so it is the file to hand to an OpenAPI client generator.

Base URL

https://api.configdirector.com/v1

Requests and responses are JSON. Send Content-Type: application/json with every request that has a body. Projects, environments, and tags are addressed by their id, a UUID; configs and segments are addressed by their key, so a URL reads the way the dashboard does:

GET https://api.configdirector.com/v1/projects/{projectId}/configs/new-checkout

Authentication

Create an API token in the dashboard under API tokens and send it as a bearer token:

Authorization: Bearer YOUR-API-TOKEN

A token belongs to the member who created it, and only that member can see, rename, or revoke it. When it is created, it is given a subset of the permissions below, and it never has more than its creator's role grants, even if the role changes later. A token can have an expiration date, which is recommended for tokens stored on a workstation. Keep tokens out of source control, and provide them through an environment variable or a secret store.

A request that is not authenticated, or that the token's permissions do not allow, is refused with 403 and a body that says why:

{
  "error": "The Authorization header is missing. Send `Authorization: Bearer <api token>`.",
  "code": "AUTHORIZATION_HEADER_MISSING"
}

Permissions

Each endpoint needs one permission, named in the endpoints table. The permissions the Admin API uses are:

Creating a config with tags needs config-settings:update as well as configs:create. Members, API tokens, SDK keys, contexts, and the audit log are managed in the dashboard only.

Terraform, OpenTofu, and the audit log

Every change made through the API is recorded in the audit log with the source API and the token's name. A client that is Terraform or OpenTofu says so with the X-SourceClient header, whose accepted values are terraform and opentofu, so the audit log shows which one made the change. Any other value is recorded as API. The Terraform provider sends the header for you.

Responses and errors

A 400 body:

{
  "errors": [
    { "name": "key", "message": "The key must be at least 4 characters long" }
  ]
}

Usage

Each request counts as one Admin API request against your organization's monthly free allowance of 10,000, and beyond it at the Pay as you go rates. Terraform applies and MCP tool calls count the same way, since both go through the API. Reading the OpenAPI document is free.

Endpoints

Projects

Environments

Configs

A config's type is one of boolean, string, integer, float, enum, url, json, or timespan, and its role is config, flag, kill-switch, or experiment. typeOptions carries the constraints of the type: isInteger, min, and max for numbers, values and valueType for an enum, useSchema and schema for JSON, unit, min, max, and allowFractions for a timespan, and secureOnly for a URL. Configs Anatomy explains each.

Segments

Tags

Examples

List the projects of the organization:

curl https://api.configdirector.com/v1/projects \
  -H "Authorization: Bearer ${CONFIGDIRECTOR_TOKEN}"

Create a temporary feature flag that starts off in every environment:

curl -X POST https://api.configdirector.com/v1/projects/${PROJECT_ID}/configs \
  -H "Authorization: Bearer ${CONFIGDIRECTOR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-checkout",
    "description": "The redesigned checkout flow",
    "role": "flag",
    "lifetime": "temporary",
    "type": "boolean",
    "defaultValue": false
  }'

Updating targeting rules

PUT /projects/{projectId}/configs/{configKey}/targets replaces the rules of one environment. The body names the environment, the default targeting rule value, and the rules in order. Each rule, condition, and percentage carries an id, a UUID you generate.

A conditional rule serves true to two named users, and the default targeting rule serves false to everyone else:

curl -X PUT https://api.configdirector.com/v1/projects/${PROJECT_ID}/configs/new-checkout/targets \
  -H "Authorization: Bearer ${CONFIGDIRECTOR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "environmentId": "'"${ENVIRONMENT_ID}"'",
    "defaultValue": false,
    "rules": [
      {
        "id": "7a6b0d1e-3b4e-4a8e-9c3b-1f2e3d4c5b6a",
        "type": "conditional",
        "order": 0,
        "target": "value",
        "value": true,
        "conditions": [
          {
            "id": "0c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
            "kind": "attribute",
            "attribute": "identifier",
            "operator": "is one of",
            "targetType": "text",
            "targetValues": ["user-101", "user-202"]
          }
        ]
      }
    ]
  }'

A rule has a type of conditional or percentage. A conditional rule holds conditions, every one of which must match, and either a target of value with the value to serve or a target of percentage with percentages, a list of { id, percentage, value } that adds up to 100. A percentage rule holds only percentages. An attribute condition tests identifier, kind, name, appName, appVersion, or traits with a trait JSON pointer, read as the targetType text, number, semver, datetime, array, or boolean, each with its own operators. A segment condition is { id, kind: "segment", operator: "in" | "not in", segmentId }. The OpenAPI document lists every operator per target type, and the Terraform provider page shows the same rules in HCL.

Rules are validated against the config's type and constraints before they are saved, exactly as in the dashboard: a value outside an integer's range, a URL that is not HTTPS on a secure-only config, or a JSON value that fails the config's schema is refused with 400.