Skip to main content
The Lightsage public API exposes the same contract used by the CLI. Use it to manage Visibility prompts, start eval runs, and work with API Performance resources from your own services and automation.
The public API uses API key authentication. It does not require browser login.

​
Base URL

All requests use this production base URL:
Use https://api.lightsage.com for API calls.

​
Authenticate

Create an API key in the Lightsage dashboard:
  1. Open Settings > API Keys.
  2. Click Create API key.
  3. Copy the key when it is shown.
Send the key on every authenticated request with the X-Lightsage-Api-Key header:
You can also store the key with the CLI and reuse the same credential for local testing:

​
Check API health

Verify that the public API is reachable:
Check that your API key is valid:

​
Explore endpoints

The sidebar groups endpoints by resource:
  • Status — health and authentication checks
  • Prompts — Visibility prompt and topic workflows
  • API Performance — eval runs, sources, targets, skills, and related resources
Use the interactive playground on each endpoint page to send requests with your API key.

​
Create an eval simulation

POST /v2/evals stores a reusable simulation matrix. Prompts, judges, agents, CLIs, and MCP servers are arrays. persona applies to every attempt, and runs controls how many times each prompt-agent pair executes.
CLI and MCP arrays can mix saved references such as {"id": "<uuid>"} with inline definitions. Eval definitions do not accept secret environment values.

​
Start an eval run

POST /v2/eval-runs accepts a saved eval or the same fields directly. This example creates and queues eight attempts:
The maximum expanded matrix is 100 attempts. Inline environment values are write-only and are not returned in public run, result, trace, or analysis payloads.

​
CLI and SDK

The CLI is generated from this same OpenAPI contract. If you prefer command-line workflows, start with the CLI Reference. Download the raw OpenAPI spec from this docs site: For generated SDKs, see the Lightsage OpenAPI repository.