REST API

Automate Weekly Planner with a personal access token. Create tokens on the account page (or via /api/tokens), then call /api/v1 with Authorization: Bearer wp_….

Base URL

Every request needs a bearer header:

Authorization: Bearer wp_…
Content-Type: application/json

Quick start

curl https://plan.ij5.dev/api/v1/me \
  -H "Authorization: Bearer wp_YOUR_TOKEN"

{
  "id": "user-id",
  "email": "you@example.com"
}

curl https://plan.ij5.dev/api/v1/boards \
  -H "Authorization: Bearer wp_YOUR_TOKEN"

How authorization works

The API never widens access beyond what the token owner can do in the app. After resolving the token, the handler impersonates the owner with the admin SDK (db.asUser({ email })), so Instant permission rules — board ownership, membership, share links, and rate limits — evaluate exactly as they do for the signed-in client.

Endpoints

Examples

Replace BOARD_ID, EVENT_ID, and wp_YOUR_TOKEN with real values from your account.

Create a board

curl -X POST https://plan.ij5.dev/api/v1/boards \
  -H "Authorization: Bearer wp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"API test","from":"2026-07-14","to":"2026-07-20"}'

{
  "board": {
    "id": "board-id",
    "name": "API test",
    "from": "2026-07-14",
    "to": "2026-07-20",
    "repeatEvery": 0,
    "colorLabels": "",
    "createdAt": 1721188800000,
    "role": "owner"
  }
}

Add an event

day is the weekday index (0 = Sunday … 6 = Saturday). start is minutes from 06:00 on that planner day; dur is duration in minutes.

curl -X POST "https://plan.ij5.dev/api/v1/boards/BOARD_ID/events" \
  -H "Authorization: Bearer wp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "day": 1,
    "title": "Standup",
    "start": 60,
    "dur": 30,
    "color": "sky",
    "memo": "Daily sync"
  }'

{
  "event": {
    "id": "event-id",
    "boardId": "board-id",
    "day": 1,
    "title": "Standup",
    "start": 60,
    "dur": 30,
    "color": "sky",
    "memo": "Daily sync",
    "createdAt": 1721188800000
  }
}

Patch an event

Send only the fields you want to change. The server merges onto the stored row and re-normalizes.

curl -X PATCH "https://plan.ij5.dev/api/v1/events/EVENT_ID" \
  -H "Authorization: Bearer wp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Standup (async)","dur": 15}'

Mark a todo done

Todos are per-user checkmarks on schedule events for a planner day.

curl -X POST https://plan.ij5.dev/api/v1/todos \
  -H "Authorization: Bearer wp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"day":"2026-07-17","eventId":"EVENT_ID"}'

Rotate the calling token

No session required — the bearer token refreshes itself. The old value stops working immediately.

curl -X POST https://plan.ij5.dev/api/v1/token/refresh \
  -H "Authorization: Bearer wp_YOUR_TOKEN"

{
  "id": "token-row-id",
  "token": "wp_NEW_SECRET",
  "prefix": "wp_abcd"
}

Token lifecycle

/api/tokens manages tokens with the signed-in session (header token = Instant refresh token):

Clients may list/revoke their own rows directly through Instant (apiTokens perms), but the hash field is unreadable and create/update are server-only.

Rate limits

Two layers, both token buckets (Instant rate limits):

1. API layer — 120 requests/minute per token (src/server/rest.js createRateLimiter); exceeding it returns 429 with Retry-After.
2. Instant $rateLimits (instant.perms.ts) — enforced inside permission rules for every writer, app or API: eventWrites (120/min burst, 2000/day sustained, keyed by auth.id, or by share secret for guests) and todoWrites (300/hour). Rule order matters: rateLimit.limit() sits last in the && chain so denied writes never consume tokens.

Errors

JSON { "error": "…" } with conventional statuses:

Instant permission failures are mapped in instantErrorStatus() inside src/server/rest-api.js (served via api/v1.js after a Vercel rewrite of /api/v1/* — Vite on Vercel has no catch-all API routes).

{ "error": "Invalid token" }

{ "error": "Not allowed" }

{ "error": "Rate limit exceeded" }

Response headers on 429:

Retry-After: 42