Skip to main content
The URLdn API is JSON over HTTPS and is included on every plan. Limits depend on your plan. All endpoints live under https://api.urldn.com/v1. Breaking changes will come as a new version in the path. The machine-readable spec is at /v1/openapi.yaml.

Quick start

  1. Open Dashboard > API keys and create a key.
  2. Copy the key. It is shown only once.
  3. Shorten your first link:

Authentication

Send your key in the Authorization header of every request:
Workspace owners and admins manage keys on the API keys page. A revoked key stops working immediately. Regenerating a key keeps its name and permissions and replaces its secret, and the old secret stops working immediately. A key acts on the whole workspace, within the permissions you gave it:
Keep keys on your server. The API accepts calls from any origin, but anything in front-end code can be read by anyone, and a leaked key acts on your whole workspace.

Plans and limits

Limits apply to your whole account, so adding keys doesn’t add requests. On Free, you can’t use bulk endpoints, custom domains, or the AI analyst, and analytics cover clicks by day for the last 7 days.

Monthly quota

Every request made with a valid key counts, including ones that fail, except those refused by the per-minute limit. On a paid plan the quota resets when your billing period renews. On Free it resets on the 1st of each month, UTC. When it runs out, the API returns 429 monthly_quota_exceeded, with the reset date in details.resetsAt. The API keys page warns you at 80% and 90%. The link and QR code limits count what is in your account now, not what you created this month. Check where you stand with GET /me. Keys created before custom domains were added to the API don’t have the domains scopes. Add them under Permissions on the API keys page. Authenticated responses include these headers:

Safe retries

Send an Idempotency-Key header on POST /links or POST /links/bulk so a retry after a timeout can’t create a second link. For 24 hours, the same key and body return the first response with Idempotent-Replayed: true. A failed attempt frees the key, so you can retry it.

Errors

Every error has the same shape. Branch on error, not on message. details is only there when there is more to say.
Every response has an X-Request-Id header. Quote it if you contact support.