# Ginkgo Playtest Analytics

> Build-scoped level analytics and build-time movement capabilities for the Ginkgo platformer. Prefer the JSON API over scraping the human dashboard.

Base URL: https://ginkgo.maxceem.bid/api/v1
Authentication: none
Read rate limits: none

## Agent documentation

- [Agent usage guide](https://ginkgo.maxceem.bid/agents.md): workflow, interpretation rules, pagination, and refresh behavior
- [OpenAPI 3.1](https://ginkgo.maxceem.bid/openapi.json): complete machine-readable API contract
- [Dashboard](https://ginkgo.maxceem.bid/): human interface backed by the same API

## Primary endpoints

- `GET /api/v1/builds`
- `GET /api/v1/builds/{build}/levels/{level}/report`
- `GET /api/v1/builds/{build}/levels/{level}/events`
- `GET /api/v1/compare?from={build}&to={build}&level={level}`
- `GET /api/v1/builds/{build}/movement-profile`
- `GET /api/v1/refresh/status`
- `POST /api/v1/refresh` (global 300-second cooldown; honor HTTP 429 and Retry-After)
- `POST /api/refresh` (equivalent compatibility path; shares the same global cooldown)

## Level tasks

- `GET /batches/{id}.md`: one batch of level tasks as a Markdown brief (every task described, full data as JSON); no sign-in
- `GET /batches/{id}/tasks/{taskId}.md`: one task of a batch as its own Markdown brief; no sign-in
- `/mcp`: MCP server for an editor's agent (OAuth sign-in): list batches, read their briefs, change the statuses of batches and tasks
- `GET /api/v1/batches?level={level}` and `GET /api/v1/batches/{id}`: batches as JSON; reading needs no sign-in, changing them does