> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
lightsage auth login
```

## Check API health

Verify that the public API is reachable:

```bash theme={null}
curl https://api.lightsage.com/v1/status
```

Check that your API key is valid:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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](https://lightsage.com/docs/cli-reference.md).

Download the raw OpenAPI spec from this docs site:

* [openapi.json](https://lightsage.com/docs/openapi.json)

For generated SDKs, see the [Lightsage OpenAPI repository](https://github.com/lightsagehq/openapi).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.