Use the API

Connect apps, scripts and Apple Shortcuts to your Widdershins account with a personal API token. A token works only for what you allow, and you can revoke it at any time.

Create a token

  1. Sign in and open Account. API tokens is under Sign-in.
  2. Name the token and choose what it can do.
  3. Copy the token straight away. It’s shown once.

Creating a token needs a sign-in from the last ten minutes. You can hold up to ten tokens at a time.

Make a request

Send the token in an Authorization header, and send JSON bodies with Content-Type: application/json. A request with a token needs no cookie and no Origin header.

curl https://widdershins.watch/api/v1/watches \
  -H "Authorization: Bearer wds_…"

Tokens are for apps, scripts and Shortcuts. A web page on another site can’t call the API with one, because the API doesn’t accept cross-origin browser requests.

Scopes

watches:read

See your watches

  • GET /api/v1/watches
watches:write

Add, edit and remove watches

Removing a watch removes its wears.

  • POST /api/v1/watches
  • PATCH /api/v1/watches/{id}
  • DELETE /api/v1/watches/{id}
  • POST /api/v1/watches/reorder
wears:read

See your wears

  • GET /api/v1/wears
  • GET /api/v1/wears/logged-today
  • GET /api/v2/wears
wears:write

Log, edit and remove wears

  • POST /api/v1/wears
  • PATCH /api/v1/wears/{id}
  • DELETE /api/v1/wears/{id}
  • POST /api/v2/wears
  • PATCH /api/v2/wears/{id}
stats:read

See your stats

Stats include your watch names and cost per wear.

  • GET /api/v1/rundown
  • GET /api/v1/stats
  • GET /api/v1/stats/{watchId}
  • GET /api/v1/year-in-review

Everything else refuses tokens: sign-in and sessions, account settings, creating or revoking tokens, sharing, import, export, notifications, photos, straps, service history, wishlist, the catalog and feedback. Every page of the site refuses them too, admin pages included.

Log a wear with Apple Shortcuts

The Log wear Shortcut lists your watches, asks which one you’re wearing, and logs it for today in your account’s timezone.

It needs a token that can “See your watches” and “Log, edit and remove wears”. When you add the Shortcut, it asks you to paste that token.

Build it yourself

  1. Text: paste your token.
  2. Get Contents of URL: https://widdershins.watch/api/v1/watches, with the header Authorization set to “Bearer ” followed by the Text.
  3. Repeat with Each item in the result: unless its status is sold, add it to a dictionary with its nickname (or brand and model) as the key and its id as the value.
  4. Choose from List: the dictionary’s keys, prompt “Which watch are you wearing?”.
  5. Get Dictionary Value: the chosen key, from the dictionary.
  6. Get Contents of URL: https://widdershins.watch/api/v1/wears, method POST, the same Authorization header, JSON body with watchId set to that value.
  7. Show Notification: “Logged” and the chosen watch when the result has an id, otherwise the result’s message.

When a request is refused

401
The token is missing, malformed or revoked.
403
The token can’t do this, or this endpoint doesn’t accept tokens.
409 on POST /api/v1/wears
That watch is already logged for that day.

Revoking a token

Revoke a token from Account at any time. It stops working on the next request. Deleting your account deletes its tokens too.

Unsent wear entries