Operations

OpenAPI Discovery

Explore the live FlagForge API contract and test authenticated requests interactively

OpenAPI Discovery

FlagForge exposes a live OpenAPI contract with every running API instance. Use the interactive Swagger UI to inspect operations and try authenticated requests, or download the machine-readable specification for code generation, validation, and integration tooling.

Discovery endpoints

If the API is running with its default local address, use these endpoints:

Resource	URL	Use it for
Interactive API docs	`http://localhost:4000/docs`	Browsing operations and sending requests with Try it out
OpenAPI document	`http://localhost:4000/openapi.json`	Loading the contract into tooling or reviewing the raw JSON
Liveness check	`http://localhost:4000/health`	Confirming that the service and database are available

The specification identifies itself as OpenAPI 3.1.0 and describes the FlagForge API, including project, environment, flag, segment, evaluation, webhook, audit, and system operations. The documented local development server is http://localhost:4000; use your deployed API's base URL when calling a self-hosted instance elsewhere.

Note:

The OpenAPI document describes the API exposed by the running service. If you change the service configuration or deploy a different version, retrieve the document from that same instance rather than relying on a copied specification.

Inspect the contract from the command line

Set the API address before using it in a shell command, then request the JSON document:

bash

BASE_URL="http://localhost:4000"
curl --fail --silent "$BASE_URL/openapi.json" | jq '{openapi, title: .info.title}'

Expected output includes the contract version and API title:

text

{
  "openapi": "3.1.0",
  "title": "FlagForge API"
}

You can save the complete document for an OpenAPI-compatible client, validator, or gateway:

bash

curl --fail --silent "$BASE_URL/openapi.json" --output flagforge-openapi.json

The document includes the route schemas and the Bearer security scheme used by the API. It is useful for discovering request and response shapes before writing an integration, while the static REST API reference provides task-oriented reference pages for individual endpoints.

Try an operation in Swagger UI

Navigate to http://localhost:4000/docs in a browser, or replace the host and port with the address of your deployed API.

Expand an operation to review its HTTP method, path parameters, request body, response schema, and authentication requirement. For example, the evaluation group includes the configuration bootstrap and flag evaluation endpoints.

Select Authorize, enter an API key as a Bearer credential, and choose Try it out. Use a server key for management operations and a client key for evaluation operations. Complete any required path or body fields, then select Execute to inspect the request, response status, and response body.

The API expects credentials in this form:

http

Authorization: Bearer <api-key>

Note:

Keep server keys private. A client key is limited to evaluation for its project; it is not a replacement for a server key when managing projects, environments, flags, segments, webhooks, or audit logs. Avoid sharing keys through screenshots, committed files, or public browser-based documentation.

OpenAPI and the static reference

Use both forms of documentation for different tasks:

When you need to…	Prefer…
Understand the available resources and endpoint purpose	The REST API reference
Confirm the exact contract served by your deployment	`/openapi.json`
Explore request fields and response schemas visually	Swagger UI at `/docs`
Send a one-off authenticated request while integrating	Swagger UI Try it out
Feed the contract into external tooling	The downloaded OpenAPI JSON

For authentication rules, see REST API authentication. For the service startup and default address, see Self-Hosting the API.

PreviousDatabase Backends NextTroubleshooting