API reference

Versioning and changelog

How versioning works

There are two levels, and they do different jobs.

The path carries the major version

Everything lives under /api/v1/. A /v2/ would be a redesign, announced well ahead, and /v1/ would keep working alongside it.

A dated header pins the details

Send ryabi-version: 2026-08-20 to lock in today's behaviour within v1. Leave the header off and you track the current version, which is the right choice for most people.

An unknown version is refused, not ignored. A typo in this header comes back as a UNKNOWN_API_VERSION immediately. A pin that is silently dropped is worse than no pin — you would believe you were protected and you would not be.

Versions you can pin

  • 2026-08-20current

A new dated version appears only when something breaking ships. Adding a field is not breaking and does not get one — if it did, you would be re-pinning every month for no reason.

Changelog

2026-08-20

pinnableHas breaking changes
  • Fixed

    API key permissions are now enforced. Until today the permissions on a key were recorded and displayed but never checked, so any valid key could perform any action its plan allowed.

    What to do: Check that each key holds the permissions your integration actually uses. A key created with only links:read can no longer delete links — which was always what it said it would do, and is now what it does.

  • Added

    Keys can be restricted by IP address or CIDR block, by time of day, by resource scope (domains and tags), and by a monthly call cap.

  • Added

    Key rolling. A roll issues a new secret immediately and keeps the old one working for a grace period you choose, so rotating no longer means an outage.

  • Added

    New key format: lnk_live_… and lnk_test_… with a trailing checksum. Test-mode keys operate on sandboxed data and never affect analytics or billing.

    What to do: Existing lnk_ + hex keys keep working and are treated as live. Roll a key to move it to the new format.

  • Added

    OAuth 2.0 delegated access, so a third-party app can act for a user without them handing over their own key.

  • Added

    New error codes for the above: INSUFFICIENT_PERMISSION, OUT_OF_SCOPE, IP_NOT_ALLOWED, OUTSIDE_ALLOWED_HOURS, API_KEY_PAUSED, API_KEY_REVOKED, BUDGET_EXCEEDED, SESSION_REQUIRED.

    What to do: Treat any 4xx you do not recognise as fatal rather than retrying it. Retrying a 403 will never succeed.

  • Changed

    API keys and billing endpoints can no longer be reached with an API key; they need a signed-in session.

    What to do: Manage keys in the dashboard. A key that could mint keys would survive its own revocation, which is why this changed.

  • Added

    Version pinning with the ryabi-version header. An unknown version is now refused rather than ignored.