Create timer

Create a one-off or recurring timer that emits a timer-fired event carrying its message.

Scope and access

  • User-scoped timers are private to the authenticated user.
  • Team-scoped timers can only be listed or managed by a team owner.
  • Repo-scoped timers can be listed and fetched by users with repo read access; creating, updating, or deleting one requires maintainer access.
  • A timer UUID is only reachable through its owning user, team, or repo scope.

Endpoints

POST /api/v1/users/{username}/timers
POST /api/v1/teams/{team_slug}/timers
POST /api/v1/teams/{team_slug}/repos/{repo_slug}/timers
POST /api/v1/users/{username}/repos/{repo_slug}/timers
Authenticated

Schedule fields

JSON / MCP CLI Behavior
run_in --run-in Fire once after a duration such as 5m or 2h.
run_at --run-at Fire once at a future RFC 3339 instant.
every_seconds --every-seconds Repeat on a fixed interval of at least one second.
time_of_day --time-of-day Repeat at a local HH:MM time.
days_of_week --days-of-week Required with time_of_day. Use all for every day, or provide a non-empty selection of three-letter names: Sun, Mon, Tue, Wed, Thu, Fri, Sat.
timezone --timezone IANA timezone for time_of_day; defaults to UTC.

Provide exactly one of run_in, run_at, every_seconds, or time_of_day. API and MCP callers may omit schedule_kind and let the server infer once or interval; the CLI always infers it from the schedule flag.

Request

message is required, trimmed, and limited to 4,000 characters. Mentions are resolved when the timer fires. Initial status may be active (the default) or paused.

{
  "message": "Check the deployment in 5 minutes @alice",
  "run_in": "5m"
}
{
  "message": "Review the release checklist",
  "time_of_day": "09:00",
  "days_of_week": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "timezone": "America/New_York",
  "status": "paused"
}

Success

201 Created with the created timer JSON.

Timer response

{
  "uuid": "8f7a2ba9-8a67-4a56-a8e8-0fe9f26717f6",
  "message": "Review the release checklist",
  "scope": "user",
  "schedule_kind": "interval",
  "schedule": "Mon, Tue, Wed, Thu, Fri at 09:00 (America/New_York)",
  "run_at": null,
  "every_seconds": null,
  "time_of_day": "09:00",
  "days_of_week": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "timezone": "America/New_York",
  "status": "active",
  "next_run_at": "2026-08-24T13:00:00Z",
  "last_run_at": null,
  "run_count": 0,
  "created_at": "2026-08-22T22:00:00Z"
}