---
title: MatchDoku HTTP API
description: Public HTTP API for health, leaderboards, guest ids, and emailed OTP sign-in.
---

# MatchDoku HTTP API

Base URL: `https://matchdoku.com`

Machine-readable description: [openapi.json](https://matchdoku.com/openapi.json)

Most gameplay happens in the browser. These endpoints are the stable HTTP surface for agents and clients.

## Health

`GET /api/health` returns `{"ok": true}` when the process is up.

## Leaderboard

`GET /api/leaderboard?difficulty={easy|medium|hard|expert|extreme}&mode={random|daily|progression}&date=YYYY-MM-DD&limit=10`

- `mode=random` is Practice.
- `date` is required for `mode=daily` (UTC calendar date, not in the future, not before 2026-01-01).
- Response lists the best run per signed-in player on that board.

## Guest id

`POST /api/guest` with `{}` issues an opaque `guestId` for unsigned play.

## Sign-in

See [auth.md](https://matchdoku.com/auth.md).

- `POST /api/auth/otp/request` with `{"email": "..."}`
- `POST /api/auth/otp/verify` with `{"email": "...", "code": "...", "guestId": "..."}`
- `GET /api/me` with `Authorization: Bearer <token>`

## Daily puzzle

`GET /api/daily-puzzle?difficulty={...}&date=YYYY-MM-DD` returns the shared daily grid for that UTC date. This is the same board the game uses.

## MCP

Read-only tools (health, leaderboard, how to play) are also exposed at `POST /mcp`. Discovery: `/.well-known/mcp/server-card.json`.