Skip to main content

​
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

​
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

​
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

​
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

​
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

​
New endpoints

​
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

​
New endpoints

​
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

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

​
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

​
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

​
New endpoints

​
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

​
New endpoints

​
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

​
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

​
New endpoints

​
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

​
Public endpoints