# Timer

A running stopwatch: one row per employee per timed record, created when the timer starts and deleted when it is discarded or its minutes are booked. There is at most one timer per employee-and-target pair. `started_at` is the only state a timer carries: elapsed time is derived from it by the client, which needs no server clock. A timer on a record type this API does not publish (an Outlook event, which the agenda really does time) renders `timeable` as the bare `{"id": N}` reference form, with `timeable_type` intact and no expansion available.

## Used by
- GET /api/v2/timers: List running timers (TimerList)
- POST /api/v2/timers: Start a timer (Timer)
- GET /api/v2/timers/{timer}: Read a timer (Timer)
- PATCH /api/v2/timers/{timer}: Correct a timer (Timer)

## Timer fields
- id (integer, required): Unique identifier.
- user_id (integer, required, server-assigned): Employee this timer belongs to. Always the authenticated user; a timer cannot be started for someone else.
- user (Ref or UserSummary, required): The employee this timer belongs to. Expanding it with `?include=user` additionally requires the `users::read` permission and a token scope covering the users prefix.
- timeable_type (string, required): The kind of record `timeable` points at; it says which branch of `timeable` applies.
- timeable_id (integer, required): The id of the record `timeable` points at.
- timeable (Ref or WorkItemSummary or EventSummary, required): The record being timed. Expanding it with `?include=timeable` additionally requires the read permission and token scope of the target's own prefix, per branch: `project_management` for a work item, events for a planning event.
- started_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): When the stopwatch was started. Elapsed time is this value against the client's own clock; the API publishes no elapsed counter.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- links (TimerLinks, required)
  - self (url, required): The canonical URI of this record.

## Variants

### TimerList

What a collection returns, and what `?view=summary` returns on a single record.

10 fields.
Identical to the detail object above.

### TimerSummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

2 fields.
Omits: user_id, user, timeable_type, timeable_id, timeable, created_at, updated_at, links

### TimerLinks

The `links` object on this resource.

Keys: self

## Polymorphic fields
- timeable: discriminated on `timeable_type`

## Example
```json
{
  "id": 1,
  "user_id": 1,
  "user": {
    "id": 1
  },
  "timeable_type": "work_item",
  "timeable_id": 41,
  "timeable": {
    "id": 1
  },
  "started_at": "2026-03-04T09:15:00Z",
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1"
  }
}
```