API overview
The Toggld HTTP API surfaces, base URL, request format, and authentication at a glance.
The Toggld API is a JSON HTTP API. The dashboard, the Node.js SDK, and the MCP server all use it, and you can call it directly.
Base URL: https://api.toggld.io
OpenAPI document: https://api.toggld.io/openapi.json. Use it to generate clients or to import the API into your tools. The endpoint pages in this reference come from the same document.
API surfaces
| Surface | Path prefix | Purpose | Credential |
|---|---|---|---|
| Management API | /api/v1 | Create, read, update, and delete flags, segments, environments, and keys. Read the audit log and analytics. | Management key |
| OFREP evaluation | /ofrep/v1 | Evaluate one flag or every flag, following the OpenFeature Remote Evaluation Protocol. | Server SDK key, management key, or public token |
| Definition sync | /sync/v1 | Download the full flag definitions of an environment for local evaluation. | Server SDK key or management key |
| Telemetry | /v1/telemetry | Send grouped evaluation counts. | Server SDK key, management key, or public token |
| Health | /health, /ready | Liveness and readiness probes. | None |
See Authentication for the exact rules.
Requests and responses
- Send request bodies as JSON with
Content-Type: application/json. - Responses are JSON, except
204 No Contentresponses. - Timestamps use ISO 8601 in UTC, such as
2026-10-31T12:00:00.000Z. - The API never takes the workspace or the environment in the URL or the body. It derives both from your credential.
curl https://api.toggld.io/api/v1/flags \
-H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY"curl https://api.toggld.io/ofrep/v1/evaluate/flags/new-checkout \
-H "Authorization: Bearer ffk_YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{ "context": { "targetingKey": "user-123" } }'Concurrency
Flag and segment reads return a version. Send it back as expectedVersion on PATCH (and on PUT for flags) to reject the write if someone else changed the resource first. The API then returns HTTP 409. See Update part of a flag.
Health checks
GET /health returns { "status": "ok" } when the API answers requests. GET /ready returns { "status": "ready" } when the API can reach its dependencies, or HTTP 503 with { "status": "not_ready" } when it cannot. Neither endpoint needs a credential.
More
Authentication
Bearer tokens, credential types, and 401 versus 403.
Errors
Error response shapes, status codes, and OFREP error codes.
Rate limits
Request budgets, HTTP 429, and Retry-After.
The endpoint pages for each surface follow in the sidebar.