# ChipClock

> The tournament clock and season tracker built for poker leagues. An agent acting on behalf of a human can create an organization, issue an API key, and start a live tournament in a single HTTP call. Human companion UI lives at https://chipclock.com.

## Try it in one request

```
curl -X POST https://chipclock.com/api/quickstart \
  -H "content-type: application/json" \
  -d '{"org_name":"Demo League"}'
```

The response contains:

- `api_key` — `ck_live_…` Bearer token. Shown exactly once. Store it.
- `org_slug` — use in every follow-up URL: `/api/orgs/{org_slug}/…`.
- `session_id` — pre-provisioned demo tournament with DEFAULT_BLINDS.
- `next_actions[]` — the first endpoints an agent will typically call.
- `expires_at` — trial orgs auto-delete 7 days after creation unless a Stripe card is added.

**Not idempotent.** A blind retry after network timeout creates a second trial org — see `hints.retry_safety` in the response.

Rate limit: 5 trial orgs per hour per IP (advisory — best-effort on serverless).

### Immediately after quickstart

```
# Start the clock (use api_key as Bearer, session_id from the response)
curl -X POST https://chipclock.com/api/orgs/{org_slug}/clock \
  -H "Authorization: Bearer {api_key}" \
  -H "content-type: application/json" \
  -d '{"sessionId":"{session_id}","action":"start"}'

# Add a player
curl -X POST https://chipclock.com/api/orgs/{org_slug}/players \
  -H "Authorization: Bearer {api_key}" \
  -H "content-type: application/json" \
  -d '{"nickname":"Alice"}'
```

## API Reference

- [OpenAPI 3.1 spec](https://chipclock.com/openapi.json) — machine-readable. Feed this to Vercel AI SDK, OpenAI Agents SDK, or any OpenAPI-aware tool-discovery framework.
- [llms-full.txt](https://chipclock.com/llms-full.txt) — expanded reference with example requests, response shapes, and common agent workflows.

## Core Concepts

- **Organization** — Tenant unit. Every row is scoped by `org_id`. URL-addressable by slug: `/api/orgs/{slug}/...`. Roles: `owner > admin > manager > player`.
- **Session** — A single tournament event. Status: `active` | `paused` | `completed` | `cancelled`. Has `blinds_config`, `buy_in_amount`, `payout_structure`, `starting_stack`.
- **Clock** — Real-time tournament timer. Advances through blind levels, auto-advances when time hits zero. Drift-corrected via `last_updated_at`.
- **Roster Player** — Named player in an org. Carries a 4-digit `pin` for self-service.
- **Check-in** — Links a roster player to a session with payment status and rebuy/addon counts.
- **Elimination** — Records when a player busts, who eliminated them, and the resulting position.
- **Payout structure** — Percentage-based prize distribution. Presets: `top3`, `top5`.
- **Table assignment** — Maps players to tables and seats. Supports seat-on-pay.
- **Trial org** — Org created via `POST /api/quickstart`. `created_via = "quickstart"`, `trial_ends_at = +7 days`. Auto-deleted by daily cleanup cron unless converted (v1.1).

## Authentication

Three modes. Agents should use API keys.

- **API key (agents)** — `Authorization: Bearer ck_live_<token>`. Org-scoped. Issued by `POST /api/quickstart` (new orgs) or `POST /api/orgs/{slug}/api-keys` (existing orgs). Revoke via the same route's DELETE.
- **Supabase session cookie (humans)** — Set by the web UI login flow. Not suitable for agents.
- **Session UUID (public, read-only)** — Public endpoints accept a session UUID as a read-only access token. Private sessions return 404.
- **Player PIN** — 4-digit PIN on `roster_players.pin` gates self-service player actions (rebuy requests, re-seat requests).

## Agent-Friendly Conventions

- **Errors** — Every non-2xx response returns a flat envelope: `{ error, code, message, hint, doc_url, next_actions }`. `error` is the legacy string for frontend compat. Agents should read `code`, `hint`, and `next_actions[]` to choose the next tool call.
- **Idempotency** — Mutating endpoints (POST, PATCH, DELETE) accept `Idempotency-Key: <any-string>` header. Same key within 24h returns the cached response. Safe to retry on timeout or network failure.
  - Exception: `POST /api/quickstart` is deliberately **not** idempotent — each call creates a fresh trial org.
- **Rate limits** — 429 responses include `Retry-After` header (seconds). Per-IP limits: 5/hour quickstart, 30/min clock, 60/min public, 10/min PIN, 5/min auth.
- **Consistent envelopes** — List endpoints return `{ data: [...], next_cursor, total }`. Single-resource endpoints return the resource directly.
- **Multi-tenancy** — Every data row belongs to exactly one org. API keys cannot cross org boundaries.

## Public Endpoints (no auth, session UUID only)

- [/api/quickstart](https://chipclock.com/api/quickstart) — POST only. Creates a trial org, session, clock, and API key in one request. See top of this file.
- [/api/health](https://chipclock.com/api/health) — Liveness probe. Returns `{ ok: true, ts }`.
- [/api/live-tournament?sessionId={uuid}](https://chipclock.com/api/live-tournament) — Single-request snapshot of all live tournament state — clock, blinds, players, eliminations, prize pool, table stats.
- [/api/clock?sessionId={uuid}](https://chipclock.com/api/clock) — Clock state only (current level, time remaining, running/paused).
- [/api/public-table-assignments?sessionId={uuid}](https://chipclock.com/api/public-table-assignments) — Who's sitting at which table and seat.
- [/api/public-player-requests?sessionId={uuid}](https://chipclock.com/api/public-player-requests) — List pending rebuy/re-seat requests (GET), submit a new request (POST, requires PIN).
- [/api/public-player-pin](https://chipclock.com/api/public-player-pin) — Set or verify a player's 4-digit PIN. Set requires nickname match to prevent PIN-spraying.
- [/api/public-feed?sessionId={uuid}](https://chipclock.com/api/public-feed) — Chronological feed of tournament events.
- [/api/public-season-standings?seasonId={uuid}](https://chipclock.com/api/public-season-standings) — Season leaderboard.

## Authenticated Endpoints (org-scoped)

All under `/api/orgs/{slug}/...`. Require a Supabase session cookie or an API key.

### Sessions (tournaments)
- `GET|POST /api/orgs/{slug}/sessions` — List or create tournaments.
- `GET|PUT|DELETE /api/orgs/{slug}/sessions/{id}` — Single tournament.
- `POST /api/orgs/{slug}/sessions/{id}/clone` — Clone for re-run.
- `GET|POST /api/orgs/{slug}/sessions/{id}/check-in` — Player check-in.
- `GET|POST /api/orgs/{slug}/sessions/{id}/rebuys` — Record rebuys/addons.
- `GET|POST /api/orgs/{slug}/sessions/{id}/results` — Final standings.
- `GET /api/orgs/{slug}/sessions/{id}/participants` — Who's in this session.
- `GET|POST|DELETE /api/orgs/{slug}/sessions/{id}/managers` — Session-level manager delegation.
- `POST /api/orgs/{slug}/sessions/{id}/notify` — Send email notifications.
- `GET|POST /api/orgs/{slug}/sessions/{id}/player-requests` — Manage rebuy/re-seat requests (host side).
- `GET|POST /api/orgs/{slug}/sessions/{id}/rsvp` — RSVP management.

### Clock
- `GET /api/orgs/{slug}/clock?sessionId={uuid}` — Authenticated clock state.
- `POST /api/orgs/{slug}/clock` — Actions: `start`, `pause`, `resume`, `next-level`, `prev-level`, `set-level`, `adjust-time`.

### Roster & players
- `GET|POST /api/orgs/{slug}/players` — Roster list/create.
- `GET|PUT|DELETE /api/orgs/{slug}/players/{playerId}` — Single player.
- `GET|POST /api/orgs/{slug}/eliminations` — Record or list eliminations.
- `GET|POST|DELETE /api/orgs/{slug}/table-assignments` — Seat management.

### Org admin
- `GET|DELETE /api/orgs/{slug}/members` — Org membership.
- `GET|PUT /api/orgs/{slug}/settings` — Org settings.
- `GET|POST|DELETE /api/orgs/{slug}/invites` — Invite tokens.
- `GET|POST|DELETE /api/orgs/{slug}/api-keys` — API key management. Cannot be invoked via a Bearer key — a key cannot manage other keys. Use the web UI.
- `GET|POST /api/orgs/{slug}/setups` — Tournament templates.
- `GET|PUT|DELETE /api/orgs/{slug}/setups/{setupId}` — Single template.
- `GET /api/orgs/{slug}/leaderboard` — Org leaderboard.
- `GET|POST /api/orgs/{slug}/seasons` — Season CRUD.
- `GET|PUT|DELETE /api/orgs/{slug}/seasons/{seasonId}` — Single season.
- `GET /api/orgs/{slug}/seasons/{seasonId}/standings` — Season standings.

### AI & billing
- `POST /api/orgs/{slug}/recommend` — AI-powered recommendation for buy-in sizing, blind structure, etc.
- `POST /api/orgs/{slug}/billing/checkout` — Create Stripe Checkout session.
- `POST /api/orgs/{slug}/billing/portal` — Create Stripe Customer Portal session.

## Common Agent Workflows

### "Start a tournament from scratch"
1. `POST /api/quickstart` with `{ "org_name": "..." }` — returns `api_key`, `org_slug`, `session_id`.
2. `POST /api/orgs/{slug}/players` with `{ "nickname": "Alice" }` — add players as needed.
3. `POST /api/orgs/{slug}/clock` with `{ sessionId, action: "start" }` — start the clock.
4. `GET /api/live-tournament?sessionId={uuid}` — confirm running state.

### "Who's still in?"
1. `GET /api/live-tournament?sessionId={uuid}` — `remaining` field + `recentEliminations[]`.

### "Suggest payouts for 27 players with a $2,700 prize pool"
1. `POST /api/orgs/{slug}/recommend` with `{ prompt: "payouts for 27 players, $2,700 prize pool" }`.

### "Knock out player X"
1. `GET /api/orgs/{slug}/players` — find player ID by nickname.
2. `POST /api/orgs/{slug}/eliminations` with `{ sessionId, rosterPlayerId, eliminatedById? }`.

## Comparisons

- [/vs/the-tournament-director](https://chipclock.com/vs/the-tournament-director)
- [/vs/blindvalet](https://chipclock.com/vs/blindvalet)

## Resources

- [Main site](https://chipclock.com)
- [Agents overview](https://chipclock.com/agents)
- [Pricing](https://chipclock.com/pricing)
- [Terms](https://chipclock.com/terms)
- [Privacy](https://chipclock.com/privacy)

## Versioning & Stability

Current API version: **v1** (stable). Breaking changes announced ≥30 days in advance. Deprecated fields remain functional for 90 days after announcement. Check `/openapi.json` `info.version` for exact build.