# API and runner reference

Public control, runner, receipt, and schema contracts.

## Scope and proof boundaries

These identifiers and routes are legitimate public integration material. A runner controls one bounded practice lifecycle; it does not grant Shopify production access or verify a receipt result.

## Identity and credentials

- `storeId` identifies the practice store; `worldId` remains an accepted compatibility alias.

- `attemptId` identifies the run returned by start and is used by later lifecycle calls.

- Control calls use the workspace API key; the agent receives only the separate Admin URL and per-store token.

## Runner lifecycle

| Action | HTTP route | MCP tool |
| --- | --- | --- |
| Start | POST /practice/stores/{storeId}/playbacks | practice_run_start |
| Status | GET /practice/playbacks/{attemptId}/state | practice_run_status |
| Checkpoint | POST /practice/playbacks/{attemptId}/checkpoint | practice_run_checkpoint |
| Advance | POST /practice/playbacks/{attemptId}/advance | practice_run_advance |
| Finish | POST /practice/playbacks/{attemptId}/finish | practice_run_finish |
| Receipt | GET /practice/playbacks/{attemptId}/report | practice_run_report |

Advance accepts exactly one of `days` or `until`. Copy the current server-owned `practiceRun.advanceCursor` object unchanged; legacy flat `expectedDay` and `expectedCallSeq` request fields remain compatible.

## Schemas and artifacts

Read [Receipt schema v1](/receipt-schema.html) for the rendered receipt schema. Public temporal exports are allowlisted summaries; private exports contain bounded internal-forensics material and belong in restricted artifacts. Same scenario, seed, clock, and agent calls produce the same modeled result; changed inputs create new evidence rather than rewriting an old receipt.

## Advanced Store-time contracts

Code-controlled runners use short-lived one-time grants bound to one workspace, store, run, current Store-time coordinate, immutable revision, and command digest. Temporal requirements are versioned JSON arrays evaluated against recorded calls and scenario time. Changing a requirement produces a new immutable revision; eligibility for Shopify Exam remains an explicit later decision rather than an effect of choosing a clock.