API

API access is a Pro and Business feature. Pro allows 2 keys, Business 10.

1. 1

   Open Dashboard → API

   Name the key after where it will run — "staging worker" beats "key 2" at 3am.

2. 2

   Select the narrowest scopes that work

   A key that only reads analytics should not carry links:write. Scopes are checked per request.

3. 3

   Copy the key immediately

   It is displayed once. Only a SHA-256 hash is stored, so it cannot be shown again — not by you and not by us.

4. 4

   Set an expiry if the key is temporary

   An expired key stops working on its own, which is better than one you meant to delete.

curl -X POST https://paddek.com/api/v1/links \
  -H "Authorization: Bearer $PADDEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationUrl": "https://shop.example.com/collections/summer",
    "slug": "summer-sale",
    "title": "Summer sale",
    "utmSource": "newsletter",
    "utmMedium": "email"
  }'

Successful responses carry a data property; failures carry an error property with a stable code. Branch on which property is present rather than on the status line — the codes are the contract.

The full endpoint list, the parameter tables and the webhook signature format are in the API reference.

Exceeding the limit returns 429 with a Retry-After header and a RATE_LIMITED error code. Back off for the number of seconds it names rather than retrying immediately.

List endpoints take page and perPage, with perPage capped at 100, and return a meta object holding page, perPage, total, totalPages and hasMore. Loop while hasMore is true.

Webhooks are a Business feature, allowing up to 20 endpoints. Each endpoint has its own secret and its own delivery log.

Every request carries an X-Paddek-Signature header of the form t=<unix seconds>,v1=<hex HMAC-SHA256>. The HMAC is computed over the timestamp, a full stop, and the raw request body. Verify against the raw body — re-serialising the JSON changes the bytes and the signature will not match.

• Reject anything whose timestamp is more than five minutes old; that is what stops a captured payload being replayed later.
• Compare signatures in constant time.
• Respond 2xx quickly and do the work afterwards. A slow endpoint is retried as if it had failed.
• Failed deliveries retry after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then stop.
• An endpoint that fails persistently is switched off automatically. There is no email about it — the endpoint shows as Paused in Dashboard → API with its consecutive-failure count beside it, so that is the screen to open when events stop arriving.

Every attempt is recorded with the status code, the response body and the next scheduled retry, so a failing integration can be diagnosed from the delivery log rather than guessed at.