# Did Codex Reset API and MCP reference

Homepage: https://didcodexreset.com/api
Skill version: 1.0.0
Install zip: https://didcodexreset.com/skills/did-codex-reset.zip

Anonymous read-only public records. No API key. Times are UTC (`…Z`).

## MCP tools

Endpoint: `https://didcodexreset.com/mcp`

| Tool | Arguments | Result |
| --- | --- | --- |
| `get_latest_reset_record` | `kind` default `all` | `{ok, data, meta}`; `data` is one record or `null` |
| `list_reset_records` | `kind`, `page=1`, `pageSize=10` | `{ok, data, meta}`; `data.items` is the page |

`kind`: `all` \| `reset_scheduled` \| `reset_completed`. `page` >= 1. `pageSize` 1–10.

Wrong types, extra argument keys, and out-of-range values are `invalid_query` tool errors. JSON integer arguments must be integers, not booleans, strings, or floating-point numbers; use `pageSize`, not `page_size`. Unknown tool names and malformed protocol messages are MCP protocol errors, not tool results.

List pagination is in `data`: `items`, `page`, `pageSize`, `total`, `totalPages`, and `hasNext`. When `hasNext` is true, increment `page` with unchanged filters. Deduplicate by `id`; pages can change as records are published. An out-of-range page is empty, and `total` counts records, not resets.

## HTTP API

Base: `https://didcodexreset.com/openapi/v1`

```bash
curl 'https://didcodexreset.com/openapi/v1/records/latest'
curl 'https://didcodexreset.com/openapi/v1/records/latest?kind=reset_completed'
curl 'https://didcodexreset.com/openapi/v1/records?kind=reset_scheduled&page=1&pageSize=10'
```

## Shared quota

20 requests / 3600s per client IP, shared by HTTP data routes and MCP query tools. Known-tool argument errors count. Initialize, `tools/list`, unknown tools, malformed protocol messages, docs, this skill, and `openapi.json` do not. Rate-limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Window`, `X-RateLimit-Reset`. HTTP 429 also sends `Retry-After`. MCP business errors use `isError` and structured error data, including `retryAfter` for limits. Protocol error HTTP statuses depend on the negotiated MCP version.

## Record rules

Sort: `kind=all` and `reset_completed` pin still-open pending schedules (soonest window first), then `announcedAt` / `completedAt` / `effectiveAt` / `id` descending. Fulfilled schedules are omitted from `all` and listed on `reset_scheduled`, which sorts by `effectiveAt` descending.

`scheduleState` on schedules: `pending`, `elapsed`, `fulfilled`, `unknown`. `elapsed` is not completed.

For the next schedule, follow `hasNext` to complete the schedule pages before selecting the earliest unexpired pending `scheduleWindow.startAt`. A pending date window can already be in progress. If pagination stops early, disclose the checked range and do not claim the candidate is the overall next schedule. See the full procedure in SKILL.md.

Manual completions use ids like `manual:…`, `source.origin=operator`, and `relatedRecordIds` for the original schedules.

## Errors

| Code | Meaning |
| --- | --- |
| `invalid_query` | Unknown, duplicate, or out-of-range arguments |
| `rate_limited` | Wait `retryAfter` seconds |
| `rate_limit_unavailable` | Limiter is on but Redis is down |
| `data_unavailable` | No published snapshot |
| `internal_error` | Server error; no internal details |

## Client install

Codex:

```bash
codex mcp add didcodexreset --url https://didcodexreset.com/mcp
```

```toml
[mcp_servers.didcodexreset]
url = "https://didcodexreset.com/mcp"
```

Skill dirs: `~/.codex/skills/` or project `.agents/skills/`

Claude Code:

```bash
claude mcp add --transport http --scope user didcodexreset https://didcodexreset.com/mcp
```

Skill dirs: `~/.claude/skills/` or project `.claude/skills/`

Cursor `mcp.json`:

```json
{
  "mcpServers": {
    "didcodexreset": {
      "url": "https://didcodexreset.com/mcp"
    }
  }
}
```

Skill dirs: `~/.cursor/skills/` or project `.cursor/skills/`

Unzip `https://didcodexreset.com/skills/did-codex-reset.zip` into the skill directory so `did-codex-reset/SKILL.md` is the skill root.