# miracle.fyi

> A pact, goal, journal, and todo system. Daily commitment-tracking with optional
> financial stakes. This file describes the agent-accessible surface.

## What you can do as an agent

Read and write a user's todos, read and check off their pacts, read and edit
their goals, and read their 3·6·9 journal — all via a REST API. Each todo has
text, optional notes, an optional "today" star (for Today list), and lifecycle
timestamps (completed_at, archived_at). Pacts are daily commitments (optionally
money-staked); you can record completions but never erase one on a staked pact.
All requests are authenticated via a single per-user bearer token the user
generates in Settings -> Connect AI tools.

## Auth

```
Authorization: Bearer USER_TOKEN
```

## Base URL

```
https://miracle.fyi/api/v1
```

## Endpoints

- `GET /todos?status=active&today=true&limit=100` — list todos
- `POST /todos` — create a todo. Body: { text, today?, notes? }. Honors Idempotency-Key header.
- `GET /todos/:id` — fetch one
- `PATCH /todos/:id` — update fields
- `POST /todos/:id/complete` — mark done
- `POST /todos/:id/uncomplete` — undo done
- `POST /todos/:id/archive` — soft-delete
- `POST /todos/:id/unarchive` — restore
- `DELETE /todos/:id` — hard delete (archived only)

## Pacts, goals, journal

Daily commitment-tracking. A *pact* is a recurring commitment (simple yes/no,
numeric/segmented, or the 3·6·9 journal), optionally backed by a money stake.
*Goals* are the five-level goal grid (bhag/month/week/day/now). The *journal*
is the 3·6·9 ritual (3 lines morning, 6 noon, 9 evening).

- `GET /pacts` — your active pacts. Each: { id, title, type, mode, stake_cents, staked, today_status, ... }.
- `GET /pacts/:id` — one pact (404 if not yours).
- `POST /pacts/:id/check` — mark KEPT for a day. Body: { date?, segment_index? }. Allowed even on money-staked pacts (a completion can only prevent a charge).
- `POST /pacts/:id/uncheck` — remove a check. Body: { date?, segment_index? }. BLOCKED on money-staked pacts → 403 staked_write_forbidden. Allowed on free pacts.
- `GET /goals` — all five levels: { goals: { bhag: { text, show_on_home, ... }, month, week, day, now } }.
- `PATCH /goals/:level` — update one level. Body: { text?, show_on_home? }.
- `GET /journal?date=YYYY-MM-DD` — read the day's sessions: { date, sessions: { morning, noon, evening } }, each { target, written, done }. READ-ONLY (journal write is not yet exposed to agents).

Money safety: the only mutation allowed on a money-staked pact is `check`.
Every other staked write (uncheck, editing the stake, archiving, deleting) is
forbidden to API tokens for now — use the app.

## Error shape

```json
{ "error": "human-readable message", "code": "machine_code" }
```

Codes you may see: bad_token, not_found, must_archive_first, text_required,
bad_status, bad_segment, date_locked, staked_write_forbidden, rate_limited,
db_error, db_unavailable.

## OpenAPI spec

https://miracle.fyi/api/v1/openapi.json

## Human-readable docs

https://miracle.fyi/docs/api — browsable reference rendered from the OpenAPI spec.
Includes per-endpoint examples and a "try it out" panel.

## MCP server

Source: in the goalgrid repo under mcp-server/. See its README for install
instructions. Configures via MIRACLE_API_KEY env var.

## Idempotency

POST /todos accepts an Idempotency-Key header. Repeating the same POST with the
same key returns the original todo (status 200) instead of creating a duplicate.
Recommended for agents that may retry on network errors.

## Versioning

The API is versioned by URL prefix. v1 will never break — additive changes only.
Breaking changes go to v2.