---
title: "Cronch developer docs: REST API, MCP server and OAuth"
description: "Build on Cronch: a REST API with scoped personal access tokens, a remote MCP server with OAuth, OpenAPI and a sandbox that needs no account."
canonical: "https://cronch.io/docs"
last-updated: "2026-10-07"
---
# Cronch developer docs. REST API, MCP server and OAuth.

Build on Cronch from your own code or agent. A REST API with scoped personal access tokens, a remote MCP server with OAuth for AI apps, an OpenAPI description, and a sandbox you can call right now without an account.

updated october 7, 2026

## How do I use the Cronch API?

Create a personal access token under Apps & MCP in your Cronch dashboard and call https://api.cronch.io/api/v1 with Authorization: Bearer. To try it first, the sandbox at https://api.cronch.io/api/v1/sandbox needs no account or token. AI apps connect to the MCP server at https://api.cronch.io/api/v1/mcp and sign in with OAuth.

## Quickstart

1. **Call the sandbox**

   No account or token. It answers with a sample day and saves nothing, so you can see the shapes before you sign up.

2. **Create a token**

   In the Cronch dashboard open **Apps & MCP** and create a personal access token. Tick **Read-only** if your code only reads. Cronch is in private beta, so an account comes from the [waitlist](https://cronch.io/#join).

3. **Call the API**

   Send the token as a bearer token. Start with today’s plan: its item ids drive every other call.

```
curl https://api.cronch.io/api/v1/sandbox/plan/today
```

```
curl https://api.cronch.io/api/v1/plan/today \
  -H "Authorization: Bearer cronch_pat_YOUR_TOKEN"

curl -X POST https://api.cronch.io/api/v1/plan/items/ITEM_ID/status \
  -H "Authorization: Bearer cronch_pat_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
  -d '{"status":"DONE"}'
```

## Sandbox

The sandbox serves the same routes and response shapes as the API, with a sample user’s day in America/New\_York seen at 12:10, so some items are done and the rest are still ahead. Writes answer like the real thing but nothing is saved: every request starts from the same sample day. Responses carry `Cronch-Sandbox: true`. It is rate limited like the API and never calls AI, email or outside services.

- **REST**: `https://api.cronch.io/api/v1/sandbox`
- **MCP**: `https://api.cronch.io/api/v1/sandbox/mcp` (no sign-in), with its own [server card](https://cronch.io/mcp/sandbox/server-card)
- **Not included**: The health check and calendar link test, which only exist on the real API.

## Authentication and scopes

**Personal access tokens** are for your own scripts, the CLI, Claude Code and Cursor. Send `Authorization: Bearer cronch_pat_…`. Every token can read; write is a scope you choose when you create it. A read-only token gets 403 on POST, PUT, PATCH and DELETE. Tokens can’t touch the password, billing or other tokens, and you can revoke one at any time from Apps & MCP.

**OAuth 2.1** is how ChatGPT, claude.ai and other MCP clients connect. It is the authorization code flow with PKCE (S256), and clients register with a Client ID Metadata Document or dynamic client registration. The user sees the scopes on the consent screen and can untick write. OAuth tokens are bound to the MCP endpoint (https://api.cronch.io/api/v1/mcp) and are refused elsewhere. Ask for the least scope you need.

| Scope | What it allows |
| --- | --- |
| cronch:read | Read today’s plan, the profile, history and the Cronch inbox. Personal tokens: every token. |
| cronch:write | Change the day: mark items done, skip or snooze them, log water, swap meals, add meetings, replan, edit the profile, ask the agent and manage inbox messages. Personal tokens: unless created read-only. |

- **Resource metadata**: [/.well-known/oauth-protected-resource/api/v1/mcp](https://api.cronch.io/.well-known/oauth-protected-resource/api/v1/mcp) (RFC 9728)
- **Server metadata**: [/.well-known/oauth-authorization-server](https://api.cronch.io/.well-known/oauth-authorization-server) (RFC 8414)
- **Authorize**: `https://api.cronch.io/api/v1/oauth/authorize`
- **Token**: `https://api.cronch.io/api/v1/oauth/token`

## Endpoints

Base URL `https://api.cronch.io/api/v1`. Request and response bodies are JSON. The [OpenAPI description](https://cronch.io/openapi.json) has every schema.

| Endpoint | Scope | What it does |
| --- | --- | --- |
| GET / | none | Describe the API. |
| GET /health | none | Check the API is up. |
| GET /plan/today | read | Get today’s plan. |
| POST /plan/replan | write | Rebuild the rest of today. |
| POST /plan/meetings | write | Set today’s meetings. |
| POST /plan/hungry | write | Get food options for right now. Counts as an AI request. |
| POST /plan/water | write | Log a glass of water. |
| POST /plan/items/{id}/swap | write | Swap a planned meal. Counts as an AI request. |
| POST /plan/items/{id}/status | write | Mark an item done or skipped. |
| POST /plan/items/{id}/snooze | write | Snooze an item. |
| GET /plan/today.ics | read | Download the rest of today as a calendar file. |
| GET /profile | read | Get the profile. |
| PUT /profile | write | Replace the profile. |
| POST /profile/calendar/test | write | Check a calendar link. |
| POST /agent | write | Ask the Cronch agent. Counts as an AI request. |
| GET /history | read | Get history and streaks. |
| GET /mailbox | read | Get the Cronch inbox. |
| PATCH /mailbox | write | Turn forwarding on or off. |
| GET /mailbox/messages | read | List inbox messages. |
| GET /mailbox/messages/{id} | read | Read a message. |
| DELETE /mailbox/messages/{id} | write | Delete a message. |

## Errors

Every error is JSON with the status, a message for people and, where it helps, a stable `code`. Validation errors list each problem in `message`.

```
{
  "statusCode": 402,
  "error": "Payment Required",
  "code": "limit_reached",
  "message": "You've used today's 25 AI requests. They reset tomorrow."
}
```

| Status | Meaning |
| --- | --- |
| 400 | The request is invalid. Fix what message says before retrying. |
| 401 | Missing, unknown, expired or revoked token. At /mcp the WWW-Authenticate header starts OAuth. |
| 402 | Code limit\_reached: today’s AI allowance is used up. It resets at midnight UTC. |
| 403 | The token lacks the scope (read-only tokens can’t write) or can’t call this route. |
| 404 | Not found. Code NO\_PROFILE: the user hasn’t finished onboarding. |
| 409, 422 | Idempotency: the key is in use by a running request, or was used for a different request. |
| 429 | Rate limited. Wait Retry-After seconds. |

## Rate limits

60 requests a minute per client by default. Every response says where you stand with `RateLimit` and `RateLimit-Policy` (the IETF RateLimit header fields) and the older `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. A 429 adds `Retry-After` in seconds.

AI requests (the agent, “I’m hungry” and meal swaps) also count toward a daily allowance: 25 a day during the beta. Past it they return 402 until midnight UTC, and every other endpoint keeps working.

```
RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=59;t=60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 60
```

## Idempotency

Networks fail mid-request. Send an `Idempotency-Key` header on POST, PUT, PATCH and DELETE, ideally a UUID as a quoted string, and retry with the same key. Cronch keeps keys for 24 hours per access token:

- the same key with the same request gets the first response again, with `Idempotent-Replayed: true`;
- the same key with a different request gets 422;
- a retry while the first request is still running gets 409, so wait and retry;
- server errors (5xx) aren’t stored, so a retry runs the request again.

Without the header, requests behave as they always have.

## Pagination

Lists come back as `{ data, meta }`, where `meta` has `page`, `limit`, `total` and `totalPages`. Pass `?page=2` and so on until `page` equals `totalPages`. Today that is the inbox (`GET /mailbox/messages`, 30 a page, newest first).

## Versioning

The version is in the path: `/api/v1`. Within v1 changes are additive: new endpoints, new optional fields and new enum values, so ignore fields you don’t know. A breaking change would ship as `/api/v2` alongside v1. Before a v1 endpoint goes away it is marked deprecated in the OpenAPI description and answers with `Deprecation` and `Sunset` headers for at least 90 days.

## MCP server

The remote MCP server at `https://api.cronch.io/api/v1/mcp` (Streamable HTTP) gives AI apps the same day through 17 tools. Read tools need `cronch:read`; tools that change the day need `cronch:write`. Setup for ChatGPT, Claude, Claude Code, Cursor and the CLI is on [Apps & MCP](https://cronch.io/mcp).

| Tool | Scope |
| --- | --- |
| get\_today | cronch:read |
| complete\_item | cronch:write |
| skip\_item | cronch:write |
| snooze\_item | cronch:write |
| im\_hungry | cronch:write |
| swap\_meal | cronch:write |
| log\_water | cronch:write |
| add\_meetings | cronch:write |
| replan | cronch:write |
| ask\_agent | cronch:write |
| get\_history | cronch:read |
| get\_profile | cronch:read |
| update\_profile | cronch:write |
| get\_inbox | cronch:read |
| get\_latest\_code | cronch:read |
| read\_message | cronch:read |
| export\_ics | cronch:read |

## Machine-readable files

- **OpenAPI 3.1**: [/openapi.json](https://cronch.io/openapi.json)
- **API catalog**: [/.well-known/api-catalog](https://cronch.io/.well-known/api-catalog) (RFC 9727)
- **Agent skill**: [SKILL.md](https://cronch.io/.well-known/agent-skills/cronch/SKILL.md), listed in [/.well-known/agent-skills/index.json](https://cronch.io/.well-known/agent-skills/index.json)
- **MCP server card**: [/mcp/server-card](https://cronch.io/mcp/server-card), listed in [/.well-known/ai-catalog.json](https://cronch.io/.well-known/ai-catalog.json)
- **Registries**: [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.cronch%2Fcronch/versions/latest) and [Glama](https://glama.ai/mcp/connectors/io.cronch/cronch), as io.cronch/cronch
- **For LLMs**: [/llms.txt](https://cronch.io/llms.txt) and [/llms-full.txt](https://cronch.io/llms-full.txt). Every page is also Markdown: send Accept: text/markdown or add .md to the URL.
- **Help**: [support@cronch.io](mailto:support@cronch.io)