> ## 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.
# Changelog
> Developer-facing Lightsage CLI and public API changes.
# Changelog
## 2026-08-10
Lightsage standardized its CLI, public API, MCP authentication, Agent Tracker,
and GitHub docs-eval commands under the `lightsage` name.
### CLI
* Released Lightsage CLI `0.6.4` with the `lightsage` executable and
`lightsagehq/tools/lightsage` Homebrew formula.
* Standardized API-key authentication on `--lightsage-api-key-auth`.
* Added `CLI_LIGHTSAGE_API_KEY_AUTH` and the `LIGHTSAGE_API_KEY` shorthand environment variable.
* Changed the default public API server to `https://api.lightsage.com`.
* Store configuration and update-check state under `~/.config/lightsage`.
### API
#### Updated authentication
* Renamed the documented public API header to `X-Lightsage-Api-Key`.
* Renamed the OpenAPI security scheme to `LightsageApiKeyAuth`.
### MCP
* Released `@lightsage/mcp` `0.1.7` for local stdio MCP clients.
* Standardized hosted MCP API-key authentication on `X-Lightsage-Api-Key`.
* Use `https://mcp.lightsage.com/mcp` for hosted connections.
### Agent Tracker
* Released Agent Tracker `0.1.13` with Lightsage-prefixed browser APIs and
declarative attributes.
* Added `initLightsagePixel` as the browser helper initializer.
* Kept the previous initializer as a deprecated compatibility alias.
* Added `data-lightsage-*` attributes for browser script configuration and declarative conversion tracking.
* Continued accepting `data-sapient-*` attributes as deprecated compatibility fallbacks.
* Made Lightsage attributes take precedence when both prefixes are present.
### Lightsage Docs Agent
* Renamed GitHub pull request commands to `/lightsage run evals`, `/lightsage status`, and `/lightsage help`.
* Moved the docs pages to `/lightsage-docs-agent/*` with redirects from the previous paths.
### Migration notes
* Update direct API and MCP clients to send the Lightsage header names.
* Re-run `lightsage auth login` after replacing an older CLI installation.
* Update local MCP configuration to use `@lightsage/mcp`.
* Update GitHub automation and saved comments to use `/lightsage` commands.
* Replace `data-sapient-*` attributes with their matching `data-lightsage-*` names.
* See [Migrate from Sapient to Lightsage](/docs/migration-guide) for complete examples.
## 2026-08-04
Lightsage replaced the prompt `is_active` boolean with the prompt lifecycle `status` across the public API and generated CLI contract.
### CLI
* Removed `--is-active` from `sapient prompts list` and `sapient prompts update`.
* Use `--status active` or `--status inactive` when listing or updating prompts.
### API
#### Updated endpoints and schemas
* `GET /v1/prompts` now filters prompt lifecycle state with the `status` query parameter.
* `PATCH /v1/prompts/{prompt_id}` now accepts `status` values of `active` or `inactive`.
* Prompt responses use the required `status` field with `active`, `inactive`, or `archived` values.
#### Removed or replaced fields
* Removed the `is_active` query parameter from `GET /v1/prompts`.
* Removed `is_active` from prompt request and response schemas.
### SDK/OpenAPI
* Updated the public OpenAPI contract without the prompt `is_active` field.
### Migration notes
* Replace `is_active=true` filters with `status=active`.
* Replace `is_active=false` filters with `status=inactive`.
* Replace prompt update payloads such as `{"is_active": true}` with `{"status": "active"}`.
## 2026-08-03
Lightsage added execution prompts to public task and opportunity responses, so API clients receive agent-ready instructions without storing separate prompt fields.
### API
#### New endpoints
| Area | Endpoint |
| -------------------- | ----------------------- |
| Prompt opportunities | `GET /v1/opportunities` |
#### Updated endpoints and schemas
* Added `execution_prompt` to `PublicTask`. Lightsage derives this prompt from the task title, goal, reasoning, evidence, source references, and metadata.
* Updated `GET /v1/tasks` so the default `status=active` response includes todo/new and in-progress tasks across persisted task batches. Use `status=todo`, `status=in_progress`, `status=done`, `status=dismissed`, `status=completed`, or `status=all` to request a specific slice.
* Added `execution_prompt` to prompt opportunity responses from `GET /v1/opportunities`. Lightsage derives this prompt from the opportunity title, description, action, evidence, and metadata.
#### Removed or replaced endpoints
* Removed `GET /v1/prompts/actions`. Use `GET /v1/opportunities` for prompt opportunities.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract with `GET /v1/opportunities`, task execution prompts, opportunity execution prompts, and the updated task status defaults.
## 2026-07-25
Lightsage added public access to the prompt visibility report, including the overall summary and the topic and prompt rows shown in the dashboard.
### API
#### New endpoints
| Area | Endpoint |
| ------------------------ | ---------------------------- |
| Prompt visibility report | `GET /v1/visibility/prompts` |
#### Updated endpoints and schemas
* Added `PublicPromptVisibilityReportResponse` with the selected date range, company, overall summary, and nested topic and active prompt rows.
* Added visibility score, visibility rank, share of voice, average position, owned-domain citation count, and run count metrics to summary, topic, and prompt rows.
* Added optional `start_date` and `end_date` query parameters. When omitted, Lightsage uses the current 30-day range.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract with the prompt visibility report endpoint and response schemas.
## 2026-07-20
Lightsage promoted the custom eval execution workflow to first-class CLI commands and added pollable run lifecycle data for active executions.
### CLI
* Added `sapient run evals` to start configured custom evals.
* Added `sapient list evals` to list active and completed custom eval executions.
* Added `sapient get run --run-id ` to poll one execution.
* Added `sapient get trace --run-id ` to retrieve a completed trace or poll trace availability while the execution is active.
* Renamed custom eval definition management from `sapient api-performance custom-evals ...` to `sapient api-performance custom-eval-definitions ...`.
* Removed `sapient eval-runs create`, `sapient eval-runs retrieve`, and `sapient api-performance custom-evals history list` from the generated CLI contract.
### API
#### New endpoints
| Area | Endpoint |
| --------------------------- | ----------------------------- |
| Start custom evals | `POST /v1/evals/run` |
| List custom eval executions | `GET /v1/evals` |
| Get execution state | `GET /v1/runs/{run_id}` |
| Get execution trace | `GET /v1/runs/{run_id}/trace` |
#### Updated endpoints and schemas
* Custom eval execution responses now include lifecycle status, stage, elapsed time, trace availability, and stable child `run_id` values.
* `GET /v1/evals` now returns a full `dashboard_url` for every execution, including the authenticated organization ID and selected run ID.
* Moved custom eval definition CRUD from `/v1/api-performance/custom-evals` to `/v1/api-performance/custom-eval-definitions`.
* Removed `POST /v1/eval-runs`, `GET /v1/eval-runs/{eval_run_id}`, and `GET /v1/api-performance/custom-evals/history`.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract with the first-class `run`, `list`, and `get` command methods.
* Removed the legacy eval-run and custom eval history operations from generated clients.
### Migration notes
* Replace custom eval `sapient eval-runs create` calls with `sapient run evals`.
* Replace custom eval history calls with `sapient list evals`.
* Poll an individual child `run_id` with `sapient get run`, then use the same ID with `sapient get trace`.
* Replace `sapient api-performance custom-evals` definition commands with `sapient api-performance custom-eval-definitions`.
## 2026-07-15
Lightsage added public Site Audit access, so API clients can list the latest website or documentation page results and inspect the prompt runs that cited a specific audited page.
### API
#### New endpoints
| Area | Endpoint |
| --------------------------- | ------------------------------ |
| Website audit results | `GET /v1/site-audit/website` |
| Documentation audit results | `GET /v1/site-audit/docs` |
| Audited page detail | `GET /v1/site-audit/{site_id}` |
#### Updated endpoints and schemas
* Added `PublicSiteAuditListResponse` with the latest audit snapshot and normalized page-level scores, checks, issues, citation metrics, and agent visits.
* Added stable public `site_id` values shared by the website, documentation, and detail endpoints.
* Added `PublicSiteAuditDetailResponse` with the selected page result and the exact prompt runs that cited it, grouped by run with prompt, platform, topic, citation count, and best position.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract with the Site Audit endpoints and response schemas.
## 2026-07-09
Lightsage added public visibility metrics for the organization resolved by your API key, so API clients can read share of voice, visibility score, and the full overview without passing a company selector.
### API
#### New endpoints
| Area | Endpoint |
| ---------- | ----------------------------- |
| Visibility | `GET /v1/visibility/current` |
| Visibility | `GET /v1/visibility/overview` |
#### Updated endpoints and schemas
* Added `PublicCurrentVisibilityResponse` with `visibility_score`, `share_of_voice`, ranks, date-range metadata, and `has_data`.
* Added `PublicVisibilityOverviewResponse`, mirroring the dashboard overview: a `snapshot` (visibility score, share of voice, average position, ranks, and total citations aggregated over the range), a daily `timeseries` of visibility score, per-platform visibility and citation series in `by_platform`, and a `competitors` comparison.
* Added optional `start_date` and `end_date` query parameters to both endpoints. When omitted, Lightsage uses the current 30-day range.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract with the new visibility endpoint.
## 2026-05-30
Lightsage updated the public API and generated CLI contract for API Performance source and operation fields. The contract now uses user-facing source and operation terminology consistently, and eval-run creation can infer the source when the selected evals or operations identify one.
### CLI
* Updated generated API Performance commands to use `--source-id` instead of `--integration-id`.
* Updated operation selection fields and flags to use `operation_id`, `operation_ids`, and `operation_paths` instead of endpoint naming.
* Updated `sapient eval-runs create` for API Performance runs so `source_id` can be inferred from `operation_ids`, `eval_ids`, or an unambiguous `source_type`.
* Updated `sapient api-performance skills list` to use `--source-id` for API Performance sources and `--skill-source-id` for skill-source filtering.
### API
#### Updated endpoints and schemas
* Updated API Performance config, evals, starter projects, actions, source targets, docs audit, and eval-run request schemas to expose `source_id` instead of `integration_id`.
* Updated API Performance eval definitions to expose `operation_id` instead of `endpoint_id`, and to include the related `source_id` and `source` object.
* Updated API Performance config and eval-run request schemas to use `operation_ids` and `operation_paths` instead of endpoint field names.
* Updated `GET /v1/api-performance/sources` responses to return `operation_count`.
* Updated skill responses to return `skill_source_id` for the skill repository/source and `source_id` for the API Performance source.
* Updated `POST /v1/eval-runs` errors to use public source terminology when a source is missing or ambiguous.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract for the updated source and operation field names.
### Migration notes
* Replace `integration_id` request fields and CLI flags with `source_id`.
* Replace `endpoint_id`, `endpoint_ids`, and `endpoint_paths` with `operation_id`, `operation_ids`, and `operation_paths`.
* Use `eval_ids`, `operation_ids`, or a single-source `source_type` when you want `sapient eval-runs create` to infer the source.
* Update skill filters to use `source_id` for API Performance sources and `skill_source_id` for skill-source IDs.
## 2026-05-29
Lightsage updated eval-run creation and CLI diagnostics so public runs are immediately pollable and dry-run output does not expose Lightsage API keys.
### CLI
* Updated `sapient --dry-run` to redact `X-Lightsage-Api-Key` and other `*-api-key` headers.
* `sapient eval-runs create` now receives a `dispatch_id` and queued child progress when Lightsage can determine the runnable work.
### API
#### Updated endpoints and schemas
* Updated `POST /v1/eval-runs` to create the durable dispatch and child queue items during the create request, while keeping `id` and `job_id` as the parent eval-run job ID.
* Updated `GET /v1/eval-runs/{eval_run_id}` to report queued dispatch progress immediately after creation.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract for the updated eval-run behavior.
### Migration notes
* Use the returned `id` as before when polling eval-run progress.
* Use `dispatch_id` when you need to correlate the run with child queue progress.
## 2026-05-27
Lightsage updated API Performance run retrieval so generated CLI and public API responses show the runtime context used for each run.
### CLI
* Updated `sapient api-performance runs retrieve` to return the stored harness prompt in `prompt_sent`.
* Added runtime trace fields to retrieved API Performance runs: `run_context_sent`, `conversation_turns`, `generated_files`, and `grader_results`.
### API
#### Updated endpoints and schemas
* Updated `GET /v1/api-performance/runs/{run_id}` to return the stored run prompt instead of the base eval definition prompt.
* Updated `EvalRunDetail` with runtime context and trace fields for docs selection, skills, generated files, conversation turns, and grader results.
* Updated API Performance `eval_overrides` on `POST /v1/eval-runs` to apply runtime fields such as `custom_prompt`, `docs_mode`, `include_env_vars`, `env_profile_ids`, `model_ids`, `compare_skills`, `skills_mode`, `skills_enabled`, `runs_per_execution`, and `starting_project_id`.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract for the updated API Performance run detail schema.
### Migration notes
* Use `docs_mode: "exclude"` in an eval override when you need a no-docs run.
* Use `docs_mode: "include"` in an eval override when you need to force docs context for a run.
## 2026-05-26
Lightsage added public eval-run orchestration and custom eval history access to the CLI and public API. You can now start durable eval jobs, poll progress, and list the history rows shown in the custom eval dashboard.
Lightsage also updated API Performance commands to resolve organization scope from the API key. Generated CLI commands no longer require a brand selector, and public responses no longer expose brand IDs.
### CLI
* Added `sapient eval-runs create`.
* Added `sapient eval-runs retrieve`.
* Added `sapient api-performance custom-evals history list`.
* Removed `--brand` from generated API Performance commands.
### API
#### New endpoints
| Area | Endpoint |
| ----------------------------------- | ------------------------------------------------------- |
| Eval runs | `POST /v1/eval-runs`, `GET /v1/eval-runs/{eval_run_id}` |
| API Performance custom eval history | `GET /v1/api-performance/custom-evals/history` |
#### Updated endpoints and schemas
* Added `PublicPromptEvalRunRequest` for starting prompt eval jobs.
* Added `PublicApiPerformanceEvalRunRequest` for starting API Performance jobs, including `source_type: "custom_evals"`.
* Added `PublicEvalRunResponse` with job ID, status, stage, dispatch ID, progress, counts, cost estimate, and timestamps.
* Added custom eval history response fields for run IDs, prompts, targets, pass/fail result, score, tool call count, latency, run time, and facets.
* Removed public brand selector parameters and request fields from API Performance endpoints.
* Removed brand ID fields from public API Performance response schemas.
* Removed the legacy `include_brand_docs` eval field. Use `docs_mode` instead.
### SDK/OpenAPI
* Regenerated the public OpenAPI contract for the new eval-runs and custom eval history operations.
* Regenerated the public OpenAPI contract without brand selectors or public brand ID fields.
### Migration notes
* Use `sapient eval-runs create` when you need to trigger prompt, API Performance, or custom eval jobs from automation.
* Use `sapient eval-runs retrieve --eval-run-id ` to poll job progress.
* Use `sapient api-performance custom-evals history list --custom-eval-id ` to list evaluated custom eval rows before retrieving a specific run.
* Remove `--brand` from API Performance CLI calls. Lightsage now resolves the organization scope from `LIGHTSAGE_API_KEY`.
* Replace `include_brand_docs` with `docs_mode` when updating eval context.
## 2026-05-23
Lightsage updated the public API and generated CLI contract for API Performance. This release introduces resource-shaped commands, API Performance actions, skill discovery, starter projects, custom evals, environment profiles, eval runtime selection fields, and source metadata for API, SDK, and CLI runs.
### CLI
* Added `sapient prompts actions list`.
* Added `sapient api-performance diagnose`.
* Added `sapient api-performance targets list`.
* Added `sapient api-performance config retrieve` and `update`.
* Added `sapient api-performance sources list`.
* Added `sapient api-performance skills list`.
* Added `sapient api-performance evals list`, `retrieve`, and `update`.
* Added `sapient api-performance custom-evals list`, `create`, `retrieve`, `update`, and `delete`.
* Added `sapient api-performance starter-projects list`, `create`, `retrieve`, `update`, and `delete`.
* Added `sapient api-performance actions list`, `refresh`, `retrieve`, `update`, and `verify`.
### API
#### New endpoints
| Area | Endpoint |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Prompt config | `GET /v1/prompts/config` |
| Prompt actions | `GET /v1/prompts/actions` |
| API Performance diagnosis | `POST /v1/api-performance/diagnose` |
| API Performance targets | `GET /v1/api-performance/targets` |
| API Performance sources | `GET /v1/api-performance/sources` |
| API Performance skills | `GET /v1/api-performance/skills` |
| API Performance eval definitions | `GET /v1/api-performance/evals`, `GET /v1/api-performance/evals/{eval_id}`, `PATCH /v1/api-performance/evals/{eval_id}` |
| API Performance custom evals | `GET /v1/api-performance/custom-evals`, `POST /v1/api-performance/custom-evals`, `GET /v1/api-performance/custom-evals/{custom_eval_id}`, `PATCH /v1/api-performance/custom-evals/{custom_eval_id}`, `DELETE /v1/api-performance/custom-evals/{custom_eval_id}` |
| API Performance starter projects | `GET /v1/api-performance/starter-projects`, `POST /v1/api-performance/starter-projects`, `GET /v1/api-performance/starter-projects/{starter_project_id}`, `PATCH /v1/api-performance/starter-projects/{starter_project_id}`, `DELETE /v1/api-performance/starter-projects/{starter_project_id}` |
| API Performance actions | `GET /v1/api-performance/actions`, `POST /v1/api-performance/actions/refresh`, `GET /v1/api-performance/actions/{action_id}`, `PATCH /v1/api-performance/actions/{action_id}`, `POST /v1/api-performance/actions/{action_id}/verify` |
#### Updated endpoints and schemas
* Updated `GET /v1/prompts` and `POST /v1/prompts` with Stainless method hints for generated CLI commands.
* Updated `GET /v1/prompts/actions` with a `tag` selector for `cited_pages`, `opportunities`, or `all`.
* Updated prompt topic, prompt retrieve, prompt update, and prompt delete operations with Stainless method hints.
* Updated `/v1/api-performance/config` to include `env_profiles` and `default_env_profile_id`.
* Updated `GET /v1/api-performance/runs` and `GET /v1/api-performance/runs/{run_id}` run summaries to include a sanitized `source` object with source `id`, `type`, `label`, and public metadata.
* Updated API Performance eval definitions with `docs_mode`, `env_profile_ids`, `skills_mode`, `skill_ids`, and `compare_skills`.
* Updated environment profile responses to return environment variable keys instead of secret values.
#### Replaced endpoint groups
* Replaced `/v1/api-performance/evaluation-config` with `/v1/api-performance/config`.
* Replaced `/v1/api-performance/interfaces` with `/v1/api-performance/sources`.
* Replaced `/v1/api-performance/operations` and operation prompt routes with `/v1/api-performance/evals` and `/v1/api-performance/custom-evals`.
* Replaced `/v1/api-performance/use-cases` with `/v1/api-performance/custom-evals`.
* Removed prompt platform and prompt cost-estimate endpoints from the current public contract.
### Migration notes
* Use `sapient api-performance config retrieve` and `update` instead of `sapient api-performance evaluation-config`.
* Use `sapient api-performance sources list` instead of `sapient api-performance interfaces list`.
* Use `sapient api-performance evals` and `custom-evals` instead of the previous operations, operation-prompts, prompts, and use-cases command groups.
* Use `sapient api-performance skills list` to discover skill IDs before setting `skills_mode selected`.
* Use `docs_mode` when controlling docs context for evals.
* Use `skills_mode selected` with one or more skill IDs to attach specific skill context to an eval.
## 2026-05-15
Lightsage's public API and generated CLI exposed the original prompt management and API Performance operation-management contract.
### CLI
* `sapient status get`
* `sapient auth status`
* `sapient prompts list`, `create`, `retrieve`, `update`, and `delete`
* `sapient prompts topics list`, `create`, `update`, and `delete`
* `sapient prompts platforms list`
* `sapient prompts estimate-cost`
* `sapient api-performance runs list` and `retrieve`
* `sapient api-performance evaluation-config retrieve` and `update`
* `sapient api-performance interfaces list`
* `sapient api-performance platforms list` and `estimate-cost`
* `sapient api-performance operations list`, `create`, `retrieve`, `update`, and `delete`
* `sapient api-performance operations prompts list` and `create`
* `sapient api-performance prompts retrieve`, `update`, and `delete`
* `sapient api-performance use-cases list`, `create`, `retrieve`, `update`, and `delete`
### API
#### Public endpoints
| Area | Endpoint |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status and auth | `GET /v1/status`, `GET /v1/auth/status` |
| Prompts | `GET /v1/prompts`, `POST /v1/prompts`, `GET /v1/prompts/{prompt_id}`, `PATCH /v1/prompts/{prompt_id}`, `DELETE /v1/prompts/{prompt_id}` |
| Prompt topics | `GET /v1/prompts/topics`, `POST /v1/prompts/topics`, `PATCH /v1/prompts/topics/{topic_id}`, `DELETE /v1/prompts/topics/{topic_id}` |
| Prompt catalog and cost | `GET /v1/prompts/platforms`, `GET /v1/prompts/estimate-cost` |
| API Performance runs | `GET /v1/api-performance/runs`, `GET /v1/api-performance/runs/{run_id}` |
| API Performance config | `GET /v1/api-performance/evaluation-config`, `PUT /v1/api-performance/evaluation-config` |
| API Performance interfaces and platforms | `GET /v1/api-performance/interfaces`, `GET /v1/api-performance/platforms`, `GET /v1/api-performance/platforms/estimate-cost` |
| API Performance operations | `GET /v1/api-performance/operations`, `POST /v1/api-performance/operations`, `GET /v1/api-performance/operations/{operation_id}`, `PATCH /v1/api-performance/operations/{operation_id}`, `DELETE /v1/api-performance/operations/{operation_id}` |
| API Performance operation prompts | `GET /v1/api-performance/operations/{operation_id}/prompts`, `POST /v1/api-performance/operations/{operation_id}/prompts`, `GET /v1/api-performance/prompts/{prompt_id}`, `PATCH /v1/api-performance/prompts/{prompt_id}`, `DELETE /v1/api-performance/prompts/{prompt_id}` |
| API Performance use cases | `GET /v1/api-performance/use-cases`, `POST /v1/api-performance/use-cases`, `GET /v1/api-performance/use-cases/{use_case_id}`, `PATCH /v1/api-performance/use-cases/{use_case_id}`, `DELETE /v1/api-performance/use-cases/{use_case_id}` |