Skip to main content

​
Base URL

http://localhost:8080

​
Versioning

All resource management endpoints are grouped under /api/v1/. The evaluation endpoint is at /api/v1/evaluate. Health probes are at /healthz and /readyz at the root (no version prefix).

​
Authentication

Togul supports two authentication schemes depending on the endpoint.

​
BearerAuth

Used for all management endpoints. Pass a JWT access token obtained from login or refresh-token. 
Authorization: Bearer <token>
Tokens are organization-scoped and expire after 1 hour. Use the refresh token (valid for 30 days) to obtain a new access token without re-authenticating.

​
ApiKeyAuth

Used for the evaluate and stream endpoints. Pass an environment-scoped API key created from the management API. 
X-API-Key: <secret>
API keys have three scopes: server, sdk, and stream. The evaluate endpoint accepts server and sdk keys; the stream endpoint accepts sdk and stream keys.

​
Request and response format

All request and response bodies use JSON. Set Content-Type: application/json on requests that include a body.

​
Status codes

Togul uses standard HTTP status codes. All successful responses return 200 OK.
CodeMeaning
200Success
400Bad request — invalid body, missing required fields, or validation failure
401Unauthorized — missing, expired, or invalid token or API key
403Forbidden — valid credentials but insufficient permissions, quota exceeded, or environment not enabled in region
404Not found — resource doesn’t exist or isn’t accessible
409Conflict — resource already exists or constraint violation
500Internal server error — typically a billing provider error
See the Errors page for full details and example payloads.

​
Error format

Error responses use a consistent JSON structure: 
{
  "code": "not_found",
  "message": "Flag not found",
  "details": null
}
FieldTypeDescription
codestringMachine-readable error code
messagestringHuman-readable description
detailsobject | nullOptional additional context

​
Endpoint groups

GroupBase pathAuth
Auth/api/v1/None or BearerAuth
Organizations/api/v1/organizationsBearerAuth
Members/api/v1/membersBearerAuth
Roles/api/v1/rolesBearerAuth
Invitations/api/v1/invitationsBearerAuth
Projects/api/v1/projectsBearerAuth
Project Members/api/v1/projects/{project_id}/membersBearerAuth
API Keys/api/v1/projects/{project_id}/api-keysBearerAuth
Environments/api/v1/projects/{project_id}/environmentsBearerAuth
Flags/api/v1/projects/{project_id}/flagsBearerAuth
Rules/api/v1/projects/{project_id}/rulesBearerAuth
Evaluate/api/v1/evaluateApiKeyAuth
Stream/api/v1/streamBearerAuth or ApiKeyAuth
Billing/api/v1/billingBearerAuth
Usage/api/v1/usageBearerAuth
Exports/api/v1/exportsBearerAuth
Account Lifecycle/api/v1/account-deletionBearerAuth
Infrastructure/healthz, /readyz, /metricsNone

Build docs developers (and LLMs) love

Get started for freeTalk to us