Developers

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

short answer

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

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.
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.
Call the API
Send the token as a bearer token. Start with today’s plan: its item ids drive every other call.

try itno token

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

your plantoken

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
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 (RFC 9728)
Server metadata: /.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 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.

402 Payment Requiredexample

{
  "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.

response headersexample

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.

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
API catalog: /.well-known/api-catalog (RFC 9727)
Agent skill: SKILL.md, listed in /.well-known/agent-skills/index.json
MCP server card: /mcp/server-card, listed in /.well-known/ai-catalog.json
Registries: Official MCP Registry and Glama, as io.cronch/cronch
For LLMs: /llms.txt and /llms-full.txt. Every page is also Markdown: send Accept: text/markdown or add .md to the URL.
Help: [email protected]

Build on your own day.

Cronch is in private beta. Join the waitlist for an account, and try the sandbox in the meantime.

Join the waitlist Read the FAQ