API Reference

Authenticate and call the Lightsage public API from your own integrations.

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.

NOTE
The public API uses API key authentication. It does not require browser login.

Base URL

All requests use this production base URL:

https://api.lightsage.com

WARNING
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:

curl https://api.lightsage.com/v1/auth/status \
  -H "X-Lightsage-Api-Key: ls_cli_your_api_key"

You can also store the key with the CLI and reuse the same credential for local testing:

lightsage auth login

Check API health

Verify that the public API is reachable:

curl https://api.lightsage.com/v1/status

Check that your API key is valid:

curl https://api.lightsage.com/v1/auth/status \
  -H "X-Lightsage-Api-Key: ls_cli_your_api_key"

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.

curl https://api.lightsage.com/v2/evals \
  -X POST \
  -H "X-Lightsage-Api-Key: ls_cli_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lightsage interface simulation",
    "prompts": [
      "Use the Lightsage CLI to create an eval.",
      "Use the Lightsage MCP server to retrieve an eval."
    ],
    "judges": ["The requested workflow completes successfully."],
    "persona": "Platform engineer",
    "agent": ["codex:gpt-5-4", "claude-code:claude-opus-4-8"],
    "clis": [
      {"install_command": "brew install lightsagehq/tools/lightsage"}
    ],
    "mcps": [{
      "name": "lightsage",
      "type": "http",
      "url": "https://mcp.lightsage.com/mcp",
      "headers": {
        "X-Lightsage-Api-Key": "${LIGHTSAGE_API_KEY}"
      }
    }],
    "runs": 2
  }'

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:

curl https://api.lightsage.com/v2/eval-runs \
  -X POST \
  -H "X-Lightsage-Api-Key: ls_cli_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["Use the CLI.", "Use the MCP server."],
    "judges": ["The workflow succeeds."],
    "agent": ["codex:gpt-5-4", "claude-code:claude-opus-4-8"],
    "mcps": [{
      "name": "lightsage",
      "type": "http",
      "url": "https://mcp.lightsage.com/mcp",
      "headers": {"X-Lightsage-Api-Key": "${LIGHTSAGE_API_KEY}"}
    }],
    "env": {"LIGHTSAGE_API_KEY": "write-only-value"},
    "runs": 2
  }'

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:

• openapi.json

For generated SDKs, see the Lightsage OpenAPI repository.