---
title: "Start, list, cancel, or clear timers"
method: POST
path: "/v1/timers"
tags: ["Utilities"]
---

# Start, list, cancel, or clear timers

`POST /v1/timers`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/timers`
- Auth: HTTP bearer

Action dispatcher for the Pomodoro / countdown timer manager.
`start` (`preset` or `duration_seconds` plus optional `label`/`sound`),
`list` (active timers), `cancel` (by `timer_id`), `clear` (all).

## Request body

- TimerRequest
  - `action` 'start' | 'list' | 'cancel' | 'clear', required
  - `preset` 'pomodoro' | 'short_break' | 'long_break': Preset duration. `action=start` only — alternative to `duration_seconds`.
  - `duration_seconds` integer: Explicit duration. `action=start` only.
  - `label` string: Display label. Optional. Falls back to the preset's default label.
  - `sound` boolean: Play a sound when the timer fires. Default true.
  - `timer_id` string: Required for `action=cancel`.

## Response `200`

Action-specific response (timer entry, list, or `{ok:true}`)

- object: Shape depends on `action`.

## Other responses

- `400`: Invalid request
- `404`: Resource not found
- `503`: Timer manager unavailable

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)