# Saram

> Saram runs synthetic personas through your product in a real browser and reports reproduced defects and persona feedback. Reference for the Saram HTTP API and MCP server.

Every page of this site has a Markdown copy at the same path with `.md` (`/agents/` is `/agents.md`),
and every public HTTP API operation has one at `/api/<operationId>.md`. The reference is built from
`@saram/platform-api` 0.16.1. The API is at https://api.saram.sh and authenticates with
`Authorization: Bearer <credential>`; the MCP server is at https://api.saram.sh/mcp.

## Docs

- [Saram documentation](https://docs.saram.sh/index.md): Reference for the Saram HTTP API and MCP server, readable by people and by agents.
- [Docs for agents](https://docs.saram.sh/agents.md): How an agent reads these docs - llms.txt, a Markdown copy of every page and operation, and the raw API and MCP descriptions.
- [Usage and billing](https://docs.saram.sh/billing.md): How Saram bills a run - persona steps weighed as Usage, the Free and Pro plans, the prepaid balance, top-ups, auto-refill and the monthly budget - and how to read your usage over the API.
- [Connect your coding agent](https://docs.saram.sh/connect-agent.md): Connect Claude Code, Cursor or Codex to the Saram MCP server, by signing in or with an API key, then check a run spec, start a run and read what it found.
- [Issues vs persona feedback](https://docs.saram.sh/issues-and-feedback.md): What a Saram run reports and how to act on each part - issues a replay tried to reproduce, the personas' verdicts and opportunities, tester errors, and the confirmation rate - and what to file as a ticket.
- [Providers and your own keys](https://docs.saram.sh/providers.md): Which model provider pays for a Saram run's model calls, how to store your own provider key, the ChatGPT login, and how a run spec's providers block names the model for each role.
- [Quickstart](https://docs.saram.sh/quickstart.md): From a dashboard API key to a first run and its results over HTTP - check the key, write a run spec, validate it for free, start the run, poll it, then read its issues, verdicts and session video.
- [The run spec](https://docs.saram.sh/run-spec.md): Every field of a Saram run spec - target, logins, personas, missions, budget, actor, trigger, connectors, files and providers - what each does, which are required, and a full example.
- [Security](https://docs.saram.sh/security.md): What Saram holds of yours, where it lives, who can read it, how you take it back, and how to report a vulnerability.

## MCP

- [MCP tools](https://docs.saram.sh/mcp/tools.md): the server instructions, and every tool with its arguments and what it returns
- [mcp-tools.json](https://docs.saram.sh/mcp-tools.json): the same tools as JSON, with their input and output schemas

## HTTP API

- [The whole reference](https://docs.saram.sh/api/index.md): all 50 operations and their schemas in one file
- [Healthz](https://docs.saram.sh/api/healthz.md): `GET /api/v1/healthz`
- [List Runs](https://docs.saram.sh/api/list_runs.md): `GET /api/v1/runs`
- [Create Run](https://docs.saram.sh/api/create_run.md): `POST /api/v1/runs`
- [Get Run](https://docs.saram.sh/api/get_run.md): `GET /api/v1/runs/{run_id}`
- [Signal Run](https://docs.saram.sh/api/signal_run.md): `POST /api/v1/runs/{run_id}/{signal}`
- [Get Artifact](https://docs.saram.sh/api/get_artifact.md): `GET /api/v1/runs/{run_id}/artifact`
- [Validate Run](https://docs.saram.sh/api/validate_run.md): `POST /api/v1/runs/validate`
- [Delete Run](https://docs.saram.sh/api/delete_run.md): `POST /api/v1/runs/{run_id}/delete`
- [Create Share Link](https://docs.saram.sh/api/create_share_link.md): `POST /api/v1/runs/{run_id}/sessions/{session_id}/shares`
- [List Share Links](https://docs.saram.sh/api/list_share_links.md): `GET /api/v1/runs/{run_id}/shares`
- [Revoke Share Link](https://docs.saram.sh/api/revoke_share_link.md): `POST /api/v1/shares/{share_id}/revoke`
- [List Sessions](https://docs.saram.sh/api/list_sessions.md): `GET /api/v1/runs/{run_id}/sessions`
- [Get Steps](https://docs.saram.sh/api/get_steps.md): `GET /api/v1/runs/{run_id}/sessions/{session_id}/steps`
- [Get Issues](https://docs.saram.sh/api/get_issues.md): `GET /api/v1/runs/{run_id}/issues`
- [Get Issue](https://docs.saram.sh/api/get_issue.md): `GET /api/v1/runs/{run_id}/issues/{issue_id}`
- [Retest Issue](https://docs.saram.sh/api/retest_issue.md): `POST /api/v1/runs/{run_id}/issues/{issue_id}/retest`
- [List Retests](https://docs.saram.sh/api/list_retests.md): `GET /api/v1/runs/{run_id}/issues/{issue_id}/retests`
- [Get Retest](https://docs.saram.sh/api/get_retest.md): `GET /api/v1/runs/{run_id}/issues/{issue_id}/retests/{retest_id}`
- [Get Verdicts](https://docs.saram.sh/api/get_verdicts.md): `GET /api/v1/runs/{run_id}/verdicts`
- [Get Opportunities](https://docs.saram.sh/api/get_opportunities.md): `GET /api/v1/runs/{run_id}/opportunities`
- [Get Tester Errors](https://docs.saram.sh/api/get_tester_errors.md): `GET /api/v1/runs/{run_id}/tester-errors`
- [Get Usage](https://docs.saram.sh/api/get_usage.md): `GET /api/v1/usage`
- [Get Usage CSV](https://docs.saram.sh/api/get_usage_csv.md): `GET /api/v1/usage.csv`
- [Billing Portal](https://docs.saram.sh/api/billing_portal.md): `POST /api/v1/billing/portal`
- [Billing Overview](https://docs.saram.sh/api/billing_overview.md): `GET /api/v1/billing`
- [Billing Auto Refill](https://docs.saram.sh/api/billing_auto_refill.md): `POST /api/v1/billing/auto-refill`
- [Billing Upgrade](https://docs.saram.sh/api/billing_upgrade.md): `POST /api/v1/billing/subscription`
- [Billing Cancel](https://docs.saram.sh/api/billing_cancel.md): `DELETE /api/v1/billing/subscription`
- [Billing Setup](https://docs.saram.sh/api/billing_setup.md): `POST /api/v1/billing/setup`
- [Billing Top Up](https://docs.saram.sh/api/billing_top_up.md): `POST /api/v1/billing/top-ups`
- [Billing Top Up Status](https://docs.saram.sh/api/billing_top_up_status.md): `GET /api/v1/billing/top-ups/{topup_id}`
- [Codex Login](https://docs.saram.sh/api/codex_login.md): `POST /api/v1/providers/codex/login`
- [Codex Status](https://docs.saram.sh/api/codex_status.md): `GET /api/v1/providers/codex`
- [Codex Disconnect](https://docs.saram.sh/api/codex_disconnect.md): `POST /api/v1/providers/codex/disconnect`
- [List Credentials](https://docs.saram.sh/api/list_credentials.md): `GET /api/v1/credentials`
- [Create Credential](https://docs.saram.sh/api/create_credential.md): `POST /api/v1/credentials`
- [Delete Credential](https://docs.saram.sh/api/delete_credential.md): `DELETE /api/v1/credentials/{name}`
- [Who Am I](https://docs.saram.sh/api/who_am_i.md): `GET /api/v1/me`
- [List API Keys](https://docs.saram.sh/api/list_api_keys.md): `GET /api/v1/api-keys`
- [Create API Key](https://docs.saram.sh/api/create_api_key.md): `POST /api/v1/api-keys`
- [Revoke API Key](https://docs.saram.sh/api/revoke_api_key.md): `DELETE /api/v1/api-keys/{key_id}`
- [List GitHub Installations](https://docs.saram.sh/api/list_github_installations.md): `GET /api/v1/github/installations`
- [List Files](https://docs.saram.sh/api/list_files.md): `GET /api/v1/files`
- [Upload File](https://docs.saram.sh/api/upload_file.md): `POST /api/v1/files`
- [Get File](https://docs.saram.sh/api/get_file.md): `GET /api/v1/files/{file_id}`
- [Delete File](https://docs.saram.sh/api/delete_file.md): `POST /api/v1/files/{file_id}/delete`
- [List Personas](https://docs.saram.sh/api/list_personas.md): `GET /api/v1/personas`
- [Get Persona](https://docs.saram.sh/api/get_persona.md): `GET /api/v1/personas/{address}`
- [Get Blob](https://docs.saram.sh/api/get_blob.md): `GET /api/v1/blobs`
- [Head Blob](https://docs.saram.sh/api/head_blob.md): `HEAD /api/v1/blobs`

## Optional

- [Complete documentation](https://docs.saram.sh/llms-full.txt): every page above in one file
- [OpenAPI description](https://docs.saram.sh/openapi.json): what the HTTP API reference is built from