API Endpoints

Base URL: https://edgeflags.net

All endpoints under /api/v1/ require a Bearer token. See Authentication.

Public endpoints

These endpoints do not require authentication.

Method	Path	Description
GET	/health	Health check
GET	/docs	Swagger UI
GET	/openapi.json	OpenAPI 3.0 schema

GET /health

curl https://edgeflags.net/health

{ "status": "ok", "environment": "production" }

---

Flag endpoints

Method	Path	Permission	Description
GET	/api/v1/flags	read:flags	List flags
GET	/api/v1/flags/:key	read:flags	Evaluate a flag
POST	/api/v1/flags	write:flags	Create a flag
PUT	/api/v1/flags/:key	write:flags	Update a flag
DELETE	/api/v1/flags/:key	write:flags	Delete a flag
PUT	/api/v1/flags/:key/environments/:env	write:flags	Set environment override
DELETE	/api/v1/flags/:key/environments/:env	write:flags	Remove environment override

GET /api/v1/flags

List all flags with pagination.

curl -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/flags?limit=50&offset=0"

{
  "flags": [
    { "key": "dark_mode", "flag": { "enabled": true, "value": true, "version": 1 } }
  ],
  "total": 1,
  "has_more": false
}

GET /api/v1/flags/:key

Evaluate a flag, optionally with user context.

curl -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/flags/dark_mode?context=%7B%22user_id%22%3A%22u_123%22%7D"

{
  "value": true,
  "type": "boolean",
  "reason": "override"
}

The reason field indicates why this value was returned: disabled, override, targeting, rollout, default, or environment_override.

POST /api/v1/flags

Create a new flag.

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new_checkout",
    "enabled": true,
    "value": false,
    "targeting": {
      "rules": [
        {
          "conditions": [
            { "property": "plan", "operator": "equals", "value": "premium" }
          ],
          "value": true
        }
      ],
      "rollout": { "percentage": 25, "attribute": "user_id" }
    },
    "environments": {
      "production": { "enabled": false }
    },
    "active_from": "2026-01-01T00:00:00Z",
    "active_until": "2026-12-31T23:59:59Z"
  }' \
  "https://edgeflags.net/api/v1/flags"

{ "success": true, "key": "new_checkout", "flag": { "enabled": true, "value": false, "version": 1, "..." : "..." } }

Returns 409 Conflict if the key already exists.

PUT /api/v1/flags/:key

Update an existing flag. Only include the fields you want to change.

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: \"1\"" \
  -d '{ "enabled": false }' \
  "https://edgeflags.net/api/v1/flags/new_checkout"

{ "success": true, "key": "new_checkout", "flag": { "enabled": false, "version": 2, "..." : "..." } }

Returns 404 Not Found if the flag doesn’t exist, 409 Conflict if the If-Match version doesn’t match.

DELETE /api/v1/flags/:key

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/flags/new_checkout"

{ "success": true, "key": "new_checkout" }

PUT /api/v1/flags/:key/environments/:env

Set an environment-specific override.

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "value": true }' \
  "https://edgeflags.net/api/v1/flags/new_checkout/environments/staging"

{ "success": true, "key": "new_checkout", "environment": "staging", "override": { "enabled": true, "value": true } }

DELETE /api/v1/flags/:key/environments/:env

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/flags/new_checkout/environments/staging"

---

Config endpoints

Method	Path	Permission	Description
GET	/api/v1/configs	read:configs	List configs
GET	/api/v1/configs/:key	read:configs	Get a config value
POST	/api/v1/configs	write:configs	Create a config
PUT	/api/v1/configs/:key	write:configs	Update a config
DELETE	/api/v1/configs/:key	write:configs	Delete a config
PUT	/api/v1/configs/:key/environments/:env	write:configs	Set environment override
DELETE	/api/v1/configs/:key/environments/:env	write:configs	Remove environment override

POST /api/v1/configs

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "api_limits",
    "value": { "requests_per_minute": 1000, "burst_limit": 2000 },
    "environments": {
      "production": { "value": { "requests_per_minute": 5000, "burst_limit": 10000 } }
    }
  }' \
  "https://edgeflags.net/api/v1/configs"

{ "success": true, "key": "api_limits", "config": { "value": { "requests_per_minute": 1000 }, "version": 1 } }

PUT /api/v1/configs/:key

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: \"1\"" \
  -d '{ "value": { "requests_per_minute": 2000 } }' \
  "https://edgeflags.net/api/v1/configs/api_limits"

GET /api/v1/configs/:key

curl -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/configs/api_limits"

{ "value": { "requests_per_minute": 1000, "burst_limit": 2000 } }

---

Segment endpoints

Method	Path	Permission	Description
GET	/api/v1/segments	write:flags	List segments
GET	/api/v1/segments/:key	write:flags	Get a segment
POST	/api/v1/segments	write:flags	Create a segment
PUT	/api/v1/segments/:key	write:flags	Update a segment
DELETE	/api/v1/segments/:key	write:flags	Delete a segment

POST /api/v1/segments

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "beta_users",
    "conditions": [
      { "property": "email", "operator": "contains", "value": "@beta.com" }
    ]
  }' \
  "https://edgeflags.net/api/v1/segments"

{ "success": true, "key": "beta_users", "segment": { "conditions": [...], "version": 1 } }

GET /api/v1/segments/:key

curl -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/segments/beta_users"

{ "key": "beta_users", "segment": { "conditions": [...], "version": 1 } }

---

Evaluation endpoint

Method	Path	Permission	Description
POST	/api/v1/evaluate	read:flags and/or read:configs	Bulk evaluate

POST /api/v1/evaluate

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "user_id": "u_123",
      "plan": "premium",
      "environment": "production",
      "custom": { "country": "US" }
    },
    "flags": ["new_checkout", "dark_mode"],
    "configs": ["payment_providers"]
  }' \
  "https://edgeflags.net/api/v1/evaluate"

{
  "flags": { "new_checkout": true, "dark_mode": true },
  "configs": { "payment_providers": { "stripe_public_key": "pk_live_xyz" } }
}

GET /api/v1/evaluate returns 405 Method Not Allowed.

---

Token endpoints

Method	Path	Permission	Description
GET	/api/v1/tokens	*	List tokens
POST	/api/v1/tokens	*	Create a token
DELETE	/api/v1/tokens/:hash	*	Delete a token

POST /api/v1/tokens

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD pipeline",
    "project_id": "default",
    "permissions": ["read:flags", "read:configs"],
    "expires_at": "2027-01-01T00:00:00Z"
  }' \
  "https://edgeflags.net/api/v1/tokens"

{
  "success": true,
  "token": "ff_defa_k1a2b3c4d5e6f7g8h9i0",
  "meta": {
    "name": "CI/CD pipeline",
    "token_prefix": "ff_defa_k1a2",
    "project_id": "default",
    "permissions": ["read:flags", "read:configs"],
    "expires_at": "2027-01-01T00:00:00Z",
    "created_at": "2026-01-15T10:00:00.000Z"
  }
}

---

Webhook endpoints

Method	Path	Permission	Description
GET	/api/v1/webhooks	*	List webhooks
POST	/api/v1/webhooks	*	Create a webhook
DELETE	/api/v1/webhooks/:id	*	Delete a webhook

POST /api/v1/webhooks

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-service.com/webhooks",
    "secret": "whsec_signing_secret",
    "events": ["flag.created", "flag.updated", "flag.deleted"]
  }' \
  "https://edgeflags.net/api/v1/webhooks"

{
  "success": true,
  "id": "a1b2c3d4e5f6a7b8",
  "config": { "url": "https://your-service.com/webhooks", "has_secret": true, "events": ["flag.created", "flag.updated", "flag.deleted"] }
}

---

Audit endpoint

Method	Path	Permission	Description
GET	/api/v1/audit	*	Query audit log

GET /api/v1/audit

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://edgeflags.net/api/v1/audit?resource_type=flag&limit=20"

{
  "entries": [
    {
      "timestamp": "2026-01-15T10:30:00.000Z",
      "actor": "ff_defa_k1a2...",
      "action": "update",
      "resource_type": "flag",
      "resource_key": "new_checkout",
      "project_id": "default",
      "before": { "..." : "..." },
      "after": { "..." : "..." }
    }
  ],
  "total": 42,
  "has_more": true
}

---

Project endpoints

Method	Path	Permission	Description
GET	/api/v1/project	any	Get project info
PUT	/api/v1/project	*	Update project
GET	/api/v1/project/environments	any	List environments
POST	/api/v1/project/environments	*	Add environment
DELETE	/api/v1/project/environments/:name	*	Remove environment

GET /api/v1/project

curl -H "Authorization: Bearer $TOKEN" \
  "https://edgeflags.net/api/v1/project"

{
  "id": "default",
  "name": "Default Project",
  "slug": "default",
  "environments": ["development", "staging", "production"]
}

POST /api/v1/project/environments

curl -X POST \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "canary" }' \
  "https://edgeflags.net/api/v1/project/environments"

{ "success": true, "environments": ["development", "staging", "production", "canary"] }