API & MCP

Everything a person can do on Focus Room Focus Timer Planner, a program or AI agent can do with the same inputs and get the identical result.

HTTP API

POST https://focusroomfocustimer.usefulweb.app/api/v1/calculate – run Focus Room Focus Timer Planner
GET https://focusroomfocustimer.usefulweb.app/api/v1/tool – inputs, output schema, examples
OpenAPI 3.1: /openapi.json · /openapi.yaml
Errors: application/problem+json; 422 includes per-field errors.

Focus Room Focus Timer Planner

Turns a focus routine into a concrete schedule: Pomodoro (25-minute blocks, 5-minute breaks, a 15-minute break after every fourth block), 52/17, or your own lengths. Enter a start date and time to get every focus block and break with clock times, the total focus and break time, and an iCalendar (.ics) file with one event per block — optionally with breaks and a reminder — that any calendar app can import. The Focus Room app uses the same planner for its timer and its calendar export.

Inputs of Focus Room Focus Timer Planner
Field	Type	Default	Description
`mode`	select (pomodoro, 52-17, custom)	"pomodoro"	Routine
`cycles`	integer	4	Focus blocks
`start`	datetime	"2026-11-16T09:00"	Start. Local date and time of the first block. Calendar events use floating local time.
`focusMinutes`	integer	45	Focus minutes (custom)
`shortBreakMinutes`	integer	10	Short break minutes (custom)
`longBreakMinutes`	integer	20	Long break minutes (custom)
`longEvery`	integer	3	Long break after every n blocks (custom, 0 = never)
`includeBreaks`	boolean	false	Put breaks in the calendar file too
`alarmMinutes`	integer	0	Reminder before each block. 0 = no reminder.
`title`	text	"Focus block"	Event title

Example request

Four Pomodoros from 9:00 with a 1-minute reminder

curl -X POST https://focusroomfocustimer.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{"mode":"pomodoro","cycles":4,"start":"2026-11-16T09:00","alarmMinutes":1,"title":"Focus block"}'

Every result contains

inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.

MCP (Model Context Protocol)

Streamable HTTP endpoint: https://focusroomfocustimer.usefulweb.app/mcp – protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake).
Tools: focusroom_focus_timer
Local stdio connector: node src/mcp-stdio.ts --tool=focusroom-focus-timer

{
  "mcpServers": {
    "focusroom-focus-timer": { "type": "http", "url": "https://focusroomfocustimer.usefulweb.app/mcp" }
  }
}