# Codex Resets Hub

> A read-only API + MCP server that mirrors Codex usage-limit reset data for fast access from mainland China.
> Source: the public API provided by codex-resets.com (an unofficial fansite that classifies @thsottiaux's
> posts); the origin site is authoritative. Community notes are adapted from codexradar.com. Watch data is an
> AI-classified forecast, not an official OpenAI commitment. Not affiliated with OpenAI.

Base URL: https://codex-reset.omicachow.com
No authentication. CORS is open. Responses support ETag / If-None-Match.

## When to use this
- "When was the last Codex limit reset?" or "how long since the last reset?" -> GET /api/v1/status
- "How likely is a reset soon, and by when?" -> GET /api/v1/status -> data.active_watch (level,
  reset_chance_percent, forecast_window, expires_at = the deadline the origin renders as "by <time>")
- "What do people think?" -> GET /api/v1/status -> data.community_poll (the origin site's headline share),
  history at GET /api/v1/poll/history
- "List / count resets" -> GET /api/v1/resets (cursor paginated) or GET /api/v1/stats
- "Show the reset pattern" -> GET /api/v1/stats (intervals, by_weekday_utc) and GET /api/v1/calendar
- "Has the forecast changed over time?" -> GET /api/v1/watch/history?steps_only=true
- "What should I do when quality drops?" / "How do I escalate to OpenAI support?" / "How do I enable Max
  reasoning?" -> GET /api/v1/knowledge?lang=en (community notes mirrored from codexradar.com)

## Endpoints
- GET /api/v1/status
- GET /api/v1/resets?limit=20&cursor=&from=&to=&order=desc
- GET /api/v1/stats
- GET /api/v1/calendar?weeks=26
- GET /api/v1/watch/history?since=&until=&limit=500&steps_only=false
- GET /api/v1/poll/history?episode_id=&limit=500
- GET /api/v1/knowledge?lang=zh|en&id=card-N&raw=false
- POST /api/v1/refresh
- GET /healthz

## MCP
POST https://codex-reset.omicachow.com/mcp (Streamable HTTP, stateless, no session id required).
Tools: get_status, list_resets, get_stats, get_reset_calendar, get_watch_history, get_knowledge, refresh_now.

## Notes and limits
- Cached: status max-age=60s, resets/stats/calendar/knowledge max-age=300s; revalidate with If-None-Match.
- Refresh is throttled to 240 requests/minute per client; 429 carries Retry-After.
- The hub re-polls upstream every 5 minutes (scheduled) and reports freshness in data.freshness of /api/v1/status.
- watch/history and poll/history only cover the period this deployment has been running.