Control my timer

Starts, pauses, resumes, stops, or discards the caller’s one canonical timer. Stop atomically creates one entry and removes the timer.

POST/api/v1/time-timer/:action

Authorization

time:write_selfapi key scoperequired

Required scope when calling with an API key.

Path parameters

actionstringrequired

Timer command

Example: stop

Request body

expected_versionnumberoptional

Required except for start

work_datestringoptional

Stop work date; defaults to today

duration_minutesnumberoptional

Optional explicit stop duration override

project_idstringoptional

Start target project

work_item_idstringoptional

Start target work item

category_keystringoptional

Required for start; optional stop override

billable_statusstringoptional"billable" | "non_billable" | "investment"

Start or stop classification

notesstringoptional

Start notes or stop override

Example request

{
  "expected_version": 1,
  "work_date": "2026-07-14",
  "notes": "Finished timer work"
}

Request

POST /api/v1/time-timer/:action

curl -X POST "https://www.digitalstack360.com/api/v1/time-timer/stop" \
  -H "Authorization: Bearer $DS_API_KEY" \
  -H "Idempotency-Key: timer-stop-2026-07-14" \
  -H "Content-Type: application/json" \
  -d '{"expected_version":1,"work_date":"2026-07-14","notes":"Finished timer work"}'

Examples use a placeholder key from your environment. Store your key in $DS_API_KEY — never commit it.

Response

200 OK

{
  "data": {
    "timer": null,
    "entry": {
      "id": "time_01k2...",
      "source": {
        "kind": "timer"
      },
      "version": 1
    }
  },
  "meta": {
    "idempotency_replayed": false,
    "self_scoped": true
  }
}

Errors

401

missing_auth

No credentials provided

401

invalid_api_key

API key is invalid or revoked

400

bad_request

Missing or invalid request fields

403

scope_insufficient

Key lacks the required write scope

409

timer_active

Start rejected because one timer is already active

404

timer_not_found

The requested command needs an active timer

409

version_conflict

Timer changed after the supplied version

409

idempotency_conflict

Stop key was reused with different command fields