# Did Codex Reset API and MCP reference

[Online API documentation](https://didcodexreset.com/api) · [llms.txt](https://didcodexreset.com/llms.txt) · [OpenAPI schema](https://didcodexreset.com/openapi/v1/openapi.json)
Skill version: 1.3.0
Install zip: https://didcodexreset.com/skills/did-codex-reset.zip

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

Read these online protocol resources once per conversation and site. Refresh them when a version or protocol change is reported, or when live tool/schema discovery conflicts with the cached copy. llms.txt is an entry-point index; do not follow every translated page. Current reset facts always come from a status or records query. If documentation is unavailable or conflicts with the live protocol, report it instead of guessing or switching transports after a `429` or `503`.

## Version checks

Installed version: read `metadata.version` from the local installed `SKILL.md`. The package template version is `1.3.0`; do not assume that value is the version of a separately installed copy.

Remote check: make a normal `GET` request to [the distributed SKILL.md](https://didcodexreset.com/skills/did-codex-reset/SKILL.md). When available, send the previously stored ETag in `If-None-Match`. Read `X-Skill-Version` and/or the returned document's `metadata.version`; the [skill zip](https://didcodexreset.com/skills/did-codex-reset.zip) is the update source. This check and the protocol-document reads do not consume the reset-query quota and must not call a data endpoint.

- Compare valid semantic versions numerically, so `1.2.10` is newer than `1.2.9`. An ETag change alone is not an upgrade, and a lower remote version is not an upgrade.
- A `304` only says the cached remote document is unchanged. Compare its stored remote version with the actual local installed version before claiming the skill is current.
- Record the last attempt, last successful check, remote version and ETag, and last version already announced in private client state keyed by site and installation directory. Do not edit local frontmatter to simulate an update. If persistent state is unavailable, keep state for the conversation and say that the 24-hour plan cannot survive a new session.
- On an unparsable or conflicting version, network failure, or missing evidence, say the check was not confirmed. Do not record success, retry tightly, block unrelated reset queries, switch API transports, or expose local configuration.

Run at most once every 24 hours unless the user asks for an immediate check. Use a native persistent scheduler only when the client supports it and the user authorized the recurring task; create or reuse one daily check. Without both conditions, do not install cron, a LaunchAgent, or another system service. Check opportunistically during skill use and optionally ask whether the user wants supported background scheduling. An explicit version-check request always gets a result, including already-current or unconfirmed; the quiet rule applies only to automatic and opportunistic checks.

When the remote version is newer and has not already been announced, send one short notice in the user's language with `installed → latest`, the [skill zip](https://didcodexreset.com/skills/did-codex-reset.zip), and [SKILL.md](https://didcodexreset.com/skills/did-codex-reset/SKILL.md). Stay quiet otherwise. A check-only authorization permits the notice, not an update. If the user authorizes an update, preserve local customizations and other skills; mention reload or a new session only when the current client requires it.

After detecting a version change, refresh llms.txt, the online API documentation, and the OpenAPI or MCP tool schema used by the active transport.

## MCP tools

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

| Tool | Arguments | Result |
| --- | --- | --- |
| `get_reset_status` | optional `lang`, optional IANA `timeZone` | `{ok, data}`; latest global/banked resets and next pending schedule |
| `get_latest_reset_record` | `kind` default `all`, optional `lang` | `{ok, data, meta}`; `data` is one record or `null` |
| `list_reset_records` | `kind`, `page=1`, `pageSize=10`, optional `lang` | `{ok, data, meta}`; `data.items` is the page |

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

`lang`: `en` \| `zh-CN` \| `zh-HK` \| `ja` \| `ko`. Omit it and the response has no `translatedText`. Set it and each record includes `translatedText`. The value is the current translation of that `text`. It is `null` when the translation is missing, not ready, or no longer matches the current body. `text` stays the source body. `lang` does not change filtering, sorting, pagination, or the shared quota.

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/status'
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/latest?lang=zh-CN'
curl 'https://didcodexreset.com/openapi/v1/records?kind=reset_scheduled&page=1&pageSize=10'
```

## Shared quota

60 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, prefer `GET /status` or `get_reset_status` and read `nextScheduled`. Follow `hasNext` through all schedule pages only for history or a custom scan. If that pagination stops early, disclose the checked range and do not claim complete coverage. See the full procedure in SKILL.md.

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

The status response contains `currentTime`, `timeZone`, `latestGlobal`, `latestBanked`, and `nextScheduled`. A `global_and_banked` completion can appear in both latest fields. Each non-null record includes `detailUrl` and its original `source.url` when one exists. `currentTime` is the query time, not data freshness or a monitor-check time.

## 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.