API

Authentication

Every request must include your personal API token as a bearer token:

Authorization: Bearer YOUR_API_TOKEN

Find and copy your token in Settings → API. You can regenerate it there at any time. Regenerating immediately invalidates the old token, so update your integrations afterwards. Keep the token secret: anyone who has it can read your collection and log wristchecks.

Base URL

All endpoints live under:

https://app.wristlog.com/api/v1

Responses are JSON.

Timezones

Every date and time in the API uses the timezone configured in your account settings, not UTC and not your client's local time. This applies consistently across every endpoint, so it's worth understanding:

• Returned timestamps (like last_worn_at) carry your timezone's offset, e.g. 2026-06-14T08:30:00+02:00.
• Day-based statistics (worn_today, days_since_last_worn, and the rolling 7/30-day windows) are calculated against the current date in your timezone.
• Logging a wristcheck with no date uses the current moment in your timezone. A date-only value like 2026-06-14 is interpreted as that calendar day in your timezone.
• The one-per-day rule (below) also uses your local day boundaries, so "today" means your today.

List your watches

GET /api/v1/watches returns every watch in your collection (active and archived) with wear statistics.

curl https://app.wristlog.com/api/v1/watches \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example response:

{
  "watches": [
    {
      "id": 42,
      "name": "Speedmaster",
      "manufacturer": "Omega",
      "model": "Moonwatch",
      "reference_number": "310.30.42.50.01.001",
      "movement_type": "Mechanical",
      "color": "#3380cc",
      "year": 2021,
      "purchase_date": "2021-06-01",
      "image_url": "https://app.wristlog.com/rails/active_storage/representations/redirect/...",
      "archived": false,
      "total_wears": 128,
      "last_worn_at": "2026-06-14T08:30:00+02:00",
      "days_since_last_worn": 1,
      "worn_today": false,
      "wears_last_7_days": 3,
      "wears_last_30_days": 11
    }
  ]
}

Fields explained:

• image_url: link to the watch photo, or null if the watch has no photo.
• total_wears: lifetime wristcheck count.
• last_worn_at: ISO 8601 timestamp of the most recent wristcheck, or null if never worn.
• days_since_last_worn: whole days since last worn, or null if never worn.
• worn_today: whether the watch already has a wristcheck logged today.
• wears_last_7_days / wears_last_30_days: wristchecks within those rolling windows.

Log a wristcheck

POST /api/v1/watches/:watch_id/wristchecks records that you wore a watch. By default the wristcheck is logged for the current moment (in your account's timezone).

curl -X POST https://app.wristlog.com/api/v1/watches/42/wristchecks \
  -H "Authorization: Bearer YOUR_API_TOKEN"

To backfill a different day, add an optional date (any value parseable as a date or datetime):

curl -X POST https://app.wristlog.com/api/v1/watches/42/wristchecks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d "date=2026-06-14"

A successful request returns 201 Created:

{ "id": 5012, "watch_id": 42, "log_date": "2026-06-14T00:00:00+02:00" }

Errors & rate limits

Errors return a JSON body. Authentication and validation failures look like:

{ "error": "Invalid API token" }

{ "errors": ["You already Wristchecked this watch today"] }

• 401 Unauthorized: missing or invalid token.
• 404 Not Found: the watch doesn't exist in your collection.
• 422 Unprocessable: validation failed (duplicate day, future date, unparseable date).
• 429 Too Many Requests: you've exceeded the rate limit.

The API is limited to 60 requests per minute per token. That's plenty for personal automations, so design yours to poll on a sensible interval rather than in a tight loop.