replay-qa-api

# Replay QA API Use the Replay QA REST API directly when a task needs Replay QA analysis. This skill is instructions-only: do not use Replay MCP tools, Codex apps, or plugin hooks as substitutes for Replay QA REST API calls. ## Replay.io Skill Prerequisite Before making any Replay QA API call, make sure the `replayio` skill in this same Codex plugin bundle has been loaded and applied for the current session. If setup is unknown, load `../replayio/SKILL.md` first and follow it before continuing. In particular, verify: - `REPLAY_API_KEY` is mapped from `SECRET_REPLAY_API_KEY` when available. - `REPLAY_QA_API_KEY` is mapped from `SECRET_REPLAY_QA_API_KEY`. - `AGENT_BROWSER_EXECUTABLE_PATH` points at Replay Chromium. - `RECORD_ALL_CONTENT` and `RECORD_REPLAY_VERBOSE` are set. - Any Replay recording referenced by Replay QA has uploaded or has a concrete recording UUID. Do not proceed with project creation or polling if this prerequisite is unknown. Load and apply the `replayio` skill first, then return to this skill. ## Authentication Replay QA API tokens are bearer tokens that start with `lqa_`. Generate one in Replay QA Settings and store it as `SECRET_REPLAY_QA_API_KEY` when the host supports project secrets. Map it before calling the API: ```bash if [ -z "${REPLAY_QA_API_KEY:-}" ] && [ -n "${SECRET_REPLAY_QA_API_KEY:-}" ]; then export REPLAY_QA_API_KEY="$SECRET_REPLAY_QA_API_KEY" fi test -n "${REPLAY_QA_API_KEY:-}" ``` Never print the token. ## Base URL Use: ```bash export REPLAY_QA_API_BASE="${REPLAY_QA_API_BASE:-https://qa.replay.io/api/v1}" ``` All requests need: ```bash -H "Authorization: Bearer $REPLAY_QA_API_KEY" -H "Content-Type: application/json" ``` ## Create A Project From A Replay Recording Use this when you already have an uploaded Replay recording UUID. When `recording_id` is present, `target_url` is not required. Required input: - `name`: clear project or scenario name. - `recording_id`: Replay recording UUID. - `instructions`: include the raw test source URL when possible and the exact failure message or stack. - `webhook_url`: optional. ```bash curl -sS -X POST "$REPLAY_QA_API_BASE/projects" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "S01 - checkout total does not update", "recording_id": "00000000-0000-0000-0000-000000000000", "instructions": "Analyze this Replay recording of a failing automated test.\n\nTest source:\nhttps://raw.githubusercontent.com/org/repo/refs/heads/branch/tests/checkout.spec.ts\n\nError:\nExpected checkout total to update after clicking Confirm Checkout.\n\nExplain the root cause and the code change that should fix it." }' ``` Save the returned project `id` and project `url` if present. If only an id is returned, the overview URL is: ```text https://qa.replay.io/p/:projectId/overview ``` ## Create A Project For Live App Exploration Use this when Replay QA should explore an app URL instead of analyzing one recording. ```bash curl -sS -X POST "$REPLAY_QA_API_BASE/projects" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Todo app smoke exploration", "target_url": "https://example.com", "instructions": "Explore the main user flows and report correctness, polish, and UX bugs." }' ``` Optional fields supported by the API include `webhook_url`, `backend_recording_url`, `backend_log_url`, `logins`, and `design_document`. Only include credentials when the user explicitly provided them for this app. ## Poll Project Status Poll every 30 seconds until the project reports completion. Status can be returned either at the top level or under `project.status`, so inspect the response shape instead of assuming one field. ```bash PROJECT_ID="..." curl -sS "$REPLAY_QA_API_BASE/projects/$PROJECT_ID/status" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" ``` For long-running analysis, report that Replay QA is still processing rather than guessing from partial data. ## Fetch Bugs List bugs: ```bash curl -sS "$REPLAY_QA_API_BASE/projects/$PROJECT_ID/bugs?page_size=100" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" ``` Filter open bugs: ```bash curl -sS "$REPLAY_QA_API_BASE/projects/$PROJECT_ID/bugs?status=open&page_size=100" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" ``` Fetch full bug detail: ```bash BUG_ID="..." curl -sS "$REPLAY_QA_API_BASE/bugs/$BUG_ID" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" ``` Use bug detail as the source of truth for root cause, reproduction steps, expected behavior, actual behavior, severity, and Replay evidence. ## Journeys, Test Runs, And Explorations List journeys: ```bash curl -sS "$REPLAY_QA_API_BASE/projects/$PROJECT_ID/journeys?page_size=100" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" ``` List test runs: ```bash curl -sS "$REPLAY_QA_API_BASE/projects/$PROJECT_ID/test-runs?page_size=100" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" ``` List explorations: ```bash curl -sS "$REPLAY_QA_API_BASE/projects/$PROJECT_ID/explorations?page_size=100" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" ``` Start another exploration: ```bash curl -sS -X POST "$REPLAY_QA_API_BASE/projects/$PROJECT_ID/explorations" \ -H "Authorization: Bearer $REPLAY_QA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Re-test checkout, saved drafts, and navigation edge cases.", "agent_count": 3 }' ``` `agent_count` must be between 1 and 10. ## Fix Workflow Discipline When Replay QA is used to guide fixes: 1. Create Replay QA projects for all selected failing recordings before fixing. 2. Wait for each selected project to finish analysis. 3. Fetch full bug details. 4. Group bugs by root cause and affected file. 5. Patch only from Replay QA evidence plus the current source file. 6. Re-run the app or tests with Replay agent-browser recording enabled. 7. Report project IDs, bug IDs, recording IDs, files changed, and remaining undiagnosed failures. Do not infer a root cause from source reading while Replay QA analysis is still pending. ## API Reference Key endpoints: | Method | Path | Purpose | |---|---|---| | `GET` | `/projects` | List projects | | `POST` | `/projects` | Create a recording-analysis or app-exploration project | | `GET` | `/projects/{project_id}` | Get project details | | `GET` | `/projects/{project_id}/status` | Get project summary/status | | `GET` | `/projects/{project_id}/bugs` | List bugs | | `GET` | `/bugs/{bug_id}` | Get bug detail | | `GET` | `/projects/{project_id}/journeys` | List journeys | | `GET` | `/projects/{project_id}/test-runs` | List test runs | | `GET` | `/projects/{project_id}/explorations` | List explorations | | `POST` | `/projects/{project_id}/explorations` | Start a new exploration | OpenAPI spec: ```text https://qa.replay.io/api/v1/openapi.json ``` ## Reporting When reporting Replay QA API work, include: - Project ID and URL, if returned. - Recording ID or target URL analyzed. - Status response summary. - Bug count and each bug ID inspected. - Root cause and recommended fix from bug detail. - Any 401, 404, rate limit, or incomplete-analysis blocker.