> ## Documentation Index
> Fetch the complete documentation index at: https://docs.urldn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Create short links, manage tags and custom domains, read click analytics, generate QR codes, and ask the AI analyst from your own code.

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`](https://api.urldn.com/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:

```bash cURL theme={null}
export URLDN_API_KEY="urldn_live_..."

curl -X POST https://api.urldn.com/v1/links \
  -H "Authorization: Bearer $URLDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/spring-launch"}'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.urldn.com/v1/links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.URLDN_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://example.com/spring-launch' })
});

if (!response.ok) {
  const { error, message } = await response.json();
  throw new Error(`${error}: ${message}`);
}
const link = await response.json();
console.log(link.shortUrl);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.urldn.com/v1/links",
    headers={"Authorization": f"Bearer {os.environ['URLDN_API_KEY']}"},
    json={"url": "https://example.com/spring-launch"},
    timeout=10,
)
response.raise_for_status()
print(response.json()["shortUrl"])
```

## Authentication

Send your key in the `Authorization` header of every request:

```http theme={null}
Authorization: Bearer urldn_live_...
```

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:

| Scope | Allows |
| - | - |
| `links:read` | Listing and reading links and tags |
| `links:write` | Creating, updating, and deleting links, and renaming and deleting tags |
| `domains:read` | Listing and reading custom domains |
| `domains:write` | Adding, verifying, and removing custom domains |
| `analytics:read` | Reading click analytics |
| `qr:write` | Creating QR codes |
| `ai:ask` | Asking the AI analyst |

> [!WARNING]
>
> 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.

| Plan | Requests per month | Requests per minute | Active keys | Links in account | QR codes | AI questions per month |
| - | - | - | - | - | - | - |
| Free | 5,000 | 60 | 1 | 10 | 5 | None |
| Pro | 100,000 | 300 | 5 | 500 | 50 | 500 |
| Business | 1,000,000 | 1,000 | 20 | 5,000 | 500 | 2,000 |
| Enterprise | Unlimited | 3,000 | 50 | Unlimited | Unlimited | Unlimited |

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`](https://docs.urldn.com/api/account/retrieve).

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:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Requests allowed per minute for your account |
| `X-RateLimit-Remaining` | Requests left in this window |
| `X-RateLimit-Reset` | When the window resets, in Unix seconds |
| `Retry-After` | On a `429`: seconds to wait before retrying |

## 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.

```json theme={null}
{
  "error": "quota_exceeded",
  "message": "You've reached your plan's limit of 500 links",
  "details": { "limit": 500, "used": 500, "plan": "pro", "upgradeUrl": "/dashboard/subscription/plans" }
}
```

Every response has an `X-Request-Id` header. Quote it if you contact support.

| Status | `error` | Meaning |
| - | - | - |
| 400 | `invalid_request` | A field is missing or not valid. `details.fields` lists each one. |
| 400 | `invalid_json` | The body is not valid JSON. |
| 400 | `invalid_cursor` | The pagination cursor is not valid. |
| 400 | `blocked_destination` | The destination is internal, private, unsafe, or points at the link itself. |
| 401 | `missing_api_key` | There is no `Authorization` header. |
| 401 | `invalid_api_key` | The key is not valid. |
| 401 | `revoked_api_key` | The key was revoked. |
| 402 | `quota_exceeded` | Your plan's links, QR codes, custom domains, or AI questions are used up. |
| 403 | `plan_required` | Your plan does not include this. |
| 403 | `insufficient_scope` | The key does not have the scope in `details.required`. |
| 403 | `domain_not_allowed` | That domain is not one of your verified domains. |
| 403 | `invalid_signature` | The QR image URL was changed or has expired. |
| 404 | `not_found` | There is no such link, tag, or domain in your account, or no such endpoint. |
| 409 | `slug_taken` | That alias is already used. |
| 409 | `domain_exists` | That domain is already in your account. |
| 409 | `domain_taken` | That domain is connected to another account. |
| 409 | `domain_cooldown` | That domain was released recently and is still reserved. |
| 409 | `idempotency_in_progress` | A request with this `Idempotency-Key` is still running. |
| 413 | `payload_too_large` | The body is over 100 KB, or 1 MB for bulk requests. |
| 422 | `idempotency_key_reused` | This `Idempotency-Key` was used with a different body. |
| 422 | `qr_not_scannable` | The link's saved QR design does not scan. |
| 429 | `rate_limited` | Too many requests. Wait for `Retry-After` seconds. |
| 429 | `monthly_quota_exceeded` | This period's requests are used up. See `details.resetsAt`. |
| 429 | `too_many_auth_failures` | Too many invalid keys from this address. |
| 500 | `internal_error` | Something went wrong on our side. |
| 503 | `ai_unavailable` | The AI analyst is unavailable. Your quota was not charged. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.