---
title: Flagpole API reference
description: Scan every Flagpole endpoint, its purpose, and the shared error contract.
url: https://pr-15-c0fdf0ef9f59.thally.app/guides/flagpole-api
---

# Flagpole API reference

Scan every Flagpole endpoint, its purpose, and the shared error contract.

All bodies are JSON. `GET /health`, `GET /version`, and `GET /ready` are
public. Every `/v1` route requires `Authorization: Bearer <token>` only when
`FLAGPOLE_API_TOKEN` is configured.

## Service probes

| Method | Path | Result |
| --- | --- | --- |
| `GET` | `/health` | `{ "status": "ok", "version": "1.1.0" }` |
| `GET` | `/version` | `{ "version": "1.1.0" }` |
| `GET` | `/ready` | `{ "status": "ready", "version": "1.1.0" }` |

## Flags

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/flags` | List flags with optional `tag`, `page`, and `perPage` query parameters. |
| `GET` | `/v1/flags/count` | Return total, enabled, and disabled counts. |
| `GET` | `/v1/flags/keys` | Return only live flag keys. |
| `POST` | `/v1/flags` | Create a flag. |
| `GET` | `/v1/flags/:key` | Read one complete flag. |
| `GET` | `/v1/flags/:key/status` | Read only the key and default switch. |
| `GET` | `/v1/flags/:key/rollout` | Read only the key and rollout percentage, or `null`. |
| `PATCH` | `/v1/flags/:key` | Replace any supplied mutable fields. At least one is required. |
| `POST` | `/v1/flags/:key/toggle` | Atomically flip the default switch. |
| `DELETE` | `/v1/flags/:key` | Delete a flag and its environment overrides; returns `204`. |
| `GET` | `/v1/flags/:key/evaluate` | Evaluate with optional `unit` and `environment`. |
| `GET` | `/v1/flags/:key/history` | Read oldest-first history with optional `limit` from 1 through 500. |

Create requires `key` and boolean `enabled`. It also accepts `description`,
integer `rolloutPercentage` from 0 through 100, and `tags`. Patch accepts the
same mutable fields except `key`.

## Tags

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/tags` | List distinct live tags with counts. |
| `GET` | `/v1/tags/:tag/flags` | List flags carrying one tag; unknown tags return `404`. |
| `DELETE` | `/v1/tags/:tag` | Retire a tag from every flag. |
| `GET` | `/v1/flags/:key/tags` | Read one flag's tag list. |
| `PUT` | `/v1/flags/:key/tags/:tag` | Attach one tag idempotently. |
| `DELETE` | `/v1/flags/:key/tags/:tag` | Detach one tag idempotently. |

Tags are unique lowercase kebab-case strings, 1–50 characters each, with at
most 10 per flag.

## Environments

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/environments` | List the environment registry. |
| `POST` | `/v1/environments` | Create a lowercase kebab-case environment. |
| `GET` | `/v1/flags/:key/environments` | List all overrides for one flag. |
| `PUT` | `/v1/flags/:key/environments/:environment` | Set `enabled`, `rolloutPercentage`, or both. |
| `DELETE` | `/v1/flags/:key/environments/:environment` | Clear one override; returns `204`. |

## Webhooks

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/webhooks` | Register an HTTPS URL and event list. |
| `GET` | `/v1/webhooks` | List subscriptions. |
| `GET` | `/v1/webhooks/:id` | Read one subscription. |
| `DELETE` | `/v1/webhooks/:id` | Delete a subscription; returns `204`. |
| `POST` | `/v1/webhooks/:id/test` | Record a test delivery; returns `202`. |
| `GET` | `/v1/webhooks/:id/deliveries` | List newest-first records with optional `status` and non-negative `limit`. |

Webhook deliveries are recorded, not sent. Subscriptions accept
`flag.created`, `flag.updated`, `flag.deleted`, and `tag.retired`; the current
release automatically records only `flag.deleted`, while the test route records
the subscription's first selected event.

## Errors

Every non-2xx response uses `{ "error": { "code", "message" } }`. Common
codes include `invalid_json`, `invalid_key`, `invalid_enabled`,
`invalid_description`, `invalid_rollout_percentage`, `invalid_tags`,
`invalid_pagination`, `invalid_limit`, `empty_update`, `unauthorized`,
`flag_not_found`, `tag_not_found`, `environment_not_found`,
`override_not_found`, `webhook_not_found`, `environment_exists`,
`flag_exists`, and `not_found`.

Use the generated **Flagpole API** tab for complete request and response
schemas.