> ## 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-09-26

Lightsage prompts now support coding-agent web access settings and optional
web-search instructions.

### CLI

* Added `run_settings` support to each prompt object passed to
  `lightsage prompts create --prompts`.
* Added `--run-settings` to `lightsage prompts update`.
* Prompt list, create, retrieve, and update output now includes the resolved
  `run_settings`.

### API

> **View API changes**
>
> #### Updated endpoints and schemas
>
> * Added optional `run_settings` to prompt batch-create items and prompt update
>   requests.
> * `search_grounding` accepts `disabled`, `enabled`, or `default` for
>   coding-agent runs. Answer-engine runs are unaffected.
> * `web_search_instruction` accepts `omit`, `append`, or `both`.
> * Prompt run list and detail responses now report the requested grounding mode,
>   observed web retrieval, and grounding qualification details.

### MCP

* Regenerated prompt tools with `run_settings` inputs and grounding fields in
  prompt and prompt-run responses.

### SDK/OpenAPI

* Regenerated the public OpenAPI, CLI, and MCP contracts with prompt-level
  grounding settings.

## 2026-09-15

Lightsage evals now support explicit setup and cleanup commands for reusable
evals and direct create-and-run requests.

### CLI

* Added repeatable `--setup-command` and `--cleanup-command` flags to
  `lightsage evals create` and `lightsage evals run`.
* `--cli` values now serialize directly as saved CLI IDs or installation
  command strings.

### API

> **View API changes**
>
> #### Updated endpoints and schemas
>
> * Added `setup_commands` and `cleanup_commands` arrays to `POST /v2/evals`,
>   `PATCH /v2/evals/{eval_id}`, and `POST /v2/eval-runs`.
> * Setup commands execute sequentially in the prepared repository before the
>   agent starts. A failed setup command prevents agent execution.
> * Cleanup commands execute best-effort after result capture and before sandbox
>   deletion. Cleanup failures do not replace the primary attempt result.
> * Saved-run requests inherit lifecycle commands from the eval. An explicit
>   empty array disables the saved commands for one launch.
> * `clis` is an ordered string array. UUID strings resolve saved CLIs; all other
>   strings are installation commands.

### SDK/OpenAPI

* Updated the public OpenAPI, CLI, and MCP contracts with lifecycle command
  fields and the string-array CLI contract.

### Migration notes

* Replace CLI objects such as `{ "install_command": "brew install ..." }`
  with the command string itself in `clis` arrays.
* Use plural `setup_commands` and `cleanup_commands` in JSON requests, or the
  singular repeatable CLI flags.

## 2026-09-14

Lightsage evals now support reusable simulation matrices across multiple
prompts, agents, CLI installations, MCP servers, and repeated attempts.

### CLI

* Added repeatable `--prompt`, `--judge`, `--agent`, `--cli`, and `--mcp`
  flags to both `lightsage evals create` and direct `lightsage evals run`.
* Added `--persona` and `--runs` to saved and direct eval workflows.
* `--cli` accepts either a saved CLI UUID or an inline installation command.
* `--mcp` accepts a saved MCP UUID, inline JSON, or `@path/to/file.json`.
* Direct runs accept repeatable `--env KEY=VALUE` values for inline MCP
  authentication and other runtime secrets.

### API

> **View API changes**
>
> #### Updated endpoints and schemas
>
> * Updated `POST /v2/evals`, `PATCH /v2/evals/{eval_id}`, and `POST
>   /v2/eval-runs` to use `prompts`, `judges`, `persona`, `agent`, `clis`, `mcps`,
>   and `runs`.
> * `agent` is an array of runnable agent IDs. `clis` is an ordered string array
>   of saved UUIDs or installation commands. `mcps` is an ordered array that can
>   mix saved `{ "id": "<uuid>" }` references with inline definitions.
> * Direct and saved runs fan out across `prompts × agent × runs`, with a maximum
>   of 100 attempts per submitted run.
> * Parent run responses now report agents, persona, prompt count, repeat count,
>   attempt count, status, and progress. Attempt analysis and trace records
>   include prompt and matrix coordinates.
> * Inline MCP definitions support `http`, `sse`, and `stdio`. `${VAR}` references
>   resolve from private run environment values before harness-specific config is
>   created.
> * Saved and inline MCP definitions now use native harness configuration across
>   Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI,
>   OpenClaw, OpenCode, Hermes, Pi, Kilo, and Grok.
> * Saved CLI IDs, inline CLI installation commands, and public skill packages
>   are installed through the same pre-execution setup before each selected
>   harness starts.

### SDK/OpenAPI

* Regenerated the public OpenAPI, CLI, and MCP contracts with typed saved and
  inline MCP unions and string CLI entries.
* Kept legacy request field aliases server-side for compatibility while hiding
  them from the current OpenAPI contract.

### Migration notes

* Replace `agent_id` with `agent: ["<agent-id>"]` in public eval requests.
* Replace `prompt` with `prompts`, and use arrays for `judges`, `clis`, and
  `mcps`.
* CLI scripts should replace `--agent-id` with repeatable `--agent` and use the
  singular repeatable `--prompt`, `--judge`, `--cli`, and `--mcp` flags.

## 2026-09-06

Lightsage simplified API Performance target payloads so callers select models and coding-agent harnesses directly.

### API

> **View API changes**
>
> #### Updated endpoints and schemas
>
> * Removed `execution_platform` from API Performance target request and response schemas.
> * Text targets now use `target_type` and `model_id` only.
> * Agent targets now use `agent_id` to select the harness and `model_id` to select the public model vendor and model.

### SDK/OpenAPI

* Updated the public OpenAPI contract so generated clients use `agent_id` for coding-agent harnesses and model IDs such as `openai/gpt-5.4`.

### Migration notes

* Remove `execution_platform` from text target payloads.
* Replace an agent target's `execution_platform` field with `agent_id`.

## 2026-09-03

Lightsage added URL-level citation reporting for GEO analysis and outreach.

### API

> **View API changes**
>
> #### New endpoints
>
> | Area | Endpoint |
> | - | - |
> | Top cited URLs | `GET /v1/visibility/citations` |
>
> #### New filters and response data
>
> * Filter cited URLs by date range, answer platform, and `all`, `owned`, or
>   `external` source type.
> * Each result includes the URL, domain, title, citation count, distinct prompt
>   count, ownership status, and citing platform names.
> * Results include only runs from currently active prompts and support a bounded
>   limit from 1 to 100 URLs.

### MCP

* Lightsage MCP can retrieve the most cited URLs for a specific platform, such
  as ChatGPT, through the visibility citations operation.

### SDK/OpenAPI

* Regenerated the public OpenAPI contract with the visibility citations
  operation and response schemas.

## 2026-08-21

Lightsage added read-only public access to the latest website Site Audit, focused on actionable page issues and their recommended fixes.

### CLI

* Released Lightsage CLI `0.6.5`.
* Added `lightsage site-audit website-list` to retrieve every audited page and its actionable issues.
* Added `lightsage site-audit retrieve --site-id <site_id>` to retrieve one page's issues and recommended fixes.

### API

> **View API changes**
>
> #### New endpoints
>
> | Area | Endpoint |
> | - | - |
> | Website audit results | `GET /v1/site-audit/website` |
> | Audited page detail | `GET /v1/site-audit/{site_id}` |
>
> #### New response data
>
> * Added `PublicSiteAuditListResponse` with a concise audit summary and page-level issue lists.
> * Added stable public `site_id` values derived from the organization and normalized page URL.
> * Added `PublicSiteAuditPage` and `PublicSiteAuditIssue` with page score, priority, issue severity, message, evidence, and recommendation.
> * The detail endpoint returns the selected page directly without unrelated citation, crawl-debug, or passing-check data.
> * The endpoints read existing audit data and never start a crawl.

### SDK/OpenAPI

* Regenerated the public OpenAPI contract and CLI with the Site Audit endpoints and response schemas.

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

> **View API changes**
>
> #### 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](https://lightsage.com/docs/migration-guide.md) 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

> **View API changes**
>
> #### 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

> **View API changes**
>
> #### 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

> **View API changes**
>
> #### 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 <run_id>` to poll one execution.
* Added `sapient get trace --run-id <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

> **View API changes**
>
> #### 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-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

> **View API changes**
>
> #### 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

> **View API changes**
>
> #### 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

> **View API changes**
>
> #### 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

> **View API changes**
>
> #### 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

> **View API changes**
>
> #### 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 <eval_run_id>` to poll job progress.
* Use `sapient api-performance custom-evals history list --custom-eval-id <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

> **View API changes**
>
> #### 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 stable generated-client operation metadata.
> * 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 operation metadata for generated clients.
> * 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

> **View API baseline**
>
> #### 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}` |


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