# URL shortener API quickstart

fwdr.link is a URL shortener API for AI agents. Create short links, change where they go, and read how often they
were opened, as JSON. Base address: `https://fwdr.link`. Everything is JSON in and JSON out. The whole API as OpenAPI 3.1:
[https://fwdr.link/openapi.json](https://fwdr.link/openapi.json).

**Available now:** free API testing: a test key without signup, test links (a preview page instead of forwarding, 24 hours), edits and counts; live keys with an email (25 free links), then US$0.01 a link from a prepaid balance; a connector (MCP) for AI assistants that can send a header, such as Claude Code, Cursor and VS Code, with your key.

**Pay as you go with x402, no account:** `POST https://fwdr.link/v1/pay/links` with `{"target": "..."}` and no key answers `402` with a `PAYMENT-REQUIRED` header (x402 v2): 0.01 USDC a link on Base. Pay with any x402 client and send the same request again with `PAYMENT-SIGNATURE`: `201` with the link. `GET` (or `HEAD`) on the same address answers the same `402` with `Allow: POST` and never takes a payment. These links can't be changed or counted later. The same payment sent again answers `200` with the same link (`"existing": true`) and is not charged again, or `409` (`payment_busy`, `Retry-After: 2`) while it is still settling. `GET https://fwdr.link/v1/pay/receipts/{tx}` finds a settled payment by its transaction hash: network, amount and short link, no key.

**Opening soon:** card top-ups (from US$10). Early access: hello@fwdr.link.

**Planned:** connector sign-in from claude.ai, ChatGPT and Grok without pasting a key; click webhooks.

## 1. Get a key

```bash
curl -s -X POST https://fwdr.link/v1/accounts/test -H 'content-type: application/json' -d '{"label":"my agent"}'
# -> 201 {"api_key": "fwdr_test_..."}
```

Send it on every call as `Authorization: Bearer fwdr_test_...`. A test key is free, needs no email and works with the
whole API. Test links show a preview page (with where a live link would go) instead of forwarding, and stop working 24
hours after they're made. Up to 500 test links a day per test account.

Live keys: `POST /v1/signup` with `{"email": "..."}` sends a 6-digit code; `POST /v1/signup/verify` with
`{"email": "...", "code": "123456"}` returns a live key and 25 free links. `POST /v1/accounts` gives a live key without
an email (top up before the first link). At the day's limit of new accounts these two answer `429` (code `signup_busy`):
try again tomorrow.
Optional `ref`: where you heard about fwdr (a word, for example the site or tool). It only helps us learn what works.

People can sign in at [https://fwdr.link/login](https://fwdr.link/login) with their email to see and change their links, keys and balance.
They can also sign in there with Google or GitHub.

## 2. Create a short link

```bash
curl -s -X POST https://fwdr.link/v1/links -H 'authorization: Bearer fwdr_test_...' -H 'content-type: application/json' \
  -d '{"target": "https://example.com/welcome"}'
```

```json
{"mode": "test", "check": "skipped", "url": "https://fwdr.link/t/q7xkm2p", "qr_url": "HTTPS://FWDR.LINK/T/Q7XKM2P/Q",
 "nfc_url": "https://fwdr.link/t/q7xkm2p/n", "domain": "fwdr.link", "slug": "t/q7xkm2p", "target": "https://example.com/welcome",
 "active": true, "expires_at": "...", "charged": "nothing (test mode)"}
```

Optional fields: `slug` (your own, live keys only), `static_params` (always added to the target, e.g.
`{"ref": "agent"}`), `allowed_params` (variables a visitor's link may pass on, e.g. `[{"name": "loc"}]`), `utm`
(default true), `forward_geo`, `forward_tag`, `tags`, `note`. The target may use placeholders:
`https://example.com/store/{loc}`.

Every target is checked first: private addresses, raw IPs, other shorteners and sites on Google's threat lists are
refused with nothing charged. Live links also get an AI review (`check` in the answer). Until a new link's target is
judged, a visitor sees a short "checking link" page (on your own domain: its fallback); nobody is forwarded to a target that wasn't judged. When you change
a target, people keep going to the previous judged one until the new one is judged, and `GET /v1/links/{slug}` shows
it as `serving` next to `target`. A check that can't run is tried again, 5 times over about ten minutes. Then a new
link is held for a person; a changed link keeps `serving` its previous target and is tried again every 30 minutes.

**Retries:** send `Idempotency-Key: <up to 100 visible characters>` with `POST /v1/links`. The same key with the same
request answers `200` with the link it made (`"existing": true`) and charges nothing; while the first request still
runs it answers `409` (`idempotency_busy`). The same key with a different request answers `409`
(`idempotency_conflict`). A key is remembered for 7 days.

## 3. Change where it goes

```bash
curl -s -X PATCH https://fwdr.link/v1/links/t/q7xkm2p -H 'authorization: Bearer fwdr_test_...' \
  -H 'content-type: application/json' -d '{"target": "https://example.com/new-page"}'
```

Only the fields you send change. The short link and its QR code stay the same. `DELETE /v1/links/{slug}` switches a
link off (links are never deleted, because they may be printed); `{"active": true}` switches it on again.
`GET /v1/history/{slug}` lists every change: when, by whom, before and after. Send `X-Fwdr-Actor: cust:42` (1 to 64
letters, digits, `:`, `_` or `-`) to have the history say which of your people or systems made a change.

## 4. Read the count

```bash
curl -s https://fwdr.link/v1/stats/t/q7xkm2p -H 'authorization: Bearer fwdr_test_...'
```

Use the `slug` from step 2 (test slugs start with `t/`). The answer has `scans` (opens by people), `people`
(different visitors; the id behind it changes every day), `bots_and_previews` (crawlers and chat apps unfurling the
link, not counted as scans), `first_scan`, `last_scan`, and lists `by_day`, `by_channel` (qr, nfc, link…),
`by_point`, `by_country`, `by_city`, `by_device`, `by_os`, `by_param` and `nfc_tags`. Add `?days=7` for another
period (default 30). `GET /v1/links` lists your links with their counts. Visitors' IP addresses are never stored.

## Connect an AI assistant

fwdr is an MCP server at `https://fwdr.link/mcp` (Streamable HTTP, JSON answers). An assistant that can send a header connects
with a key from step 1; a test key makes free preview links.

**Claude Code:**

```bash
claude mcp add --transport http fwdr https://fwdr.link/mcp --header "Authorization: Bearer <your key>"
```

**Cursor** (`~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "fwdr": {
      "url": "https://fwdr.link/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}
```

**Any other MCP client** (VS Code, Windsurf, Zed…): transport Streamable HTTP, address `https://fwdr.link/mcp`, header
`Authorization: Bearer <your key>`. In VS Code's `.vscode/mcp.json`:

```json
{ "servers": { "fwdr": { "type": "http", "url": "https://fwdr.link/mcp", "headers": { "Authorization": "Bearer <your key>" } } } }
```

The tools:

- `create_link`: Make a short link
- `update_link`: Change a link
- `get_link`: Show a link
- `list_links`: List links
- `switch_link_off`: Switch a link off
- `switch_link_on`: Switch a link on
- `link_stats`: Link numbers
- `link_history`: Link history
- `qr_code`: QR code
- `register_nfc_tag`: Register an NFC chip
- `list_nfc_tags`: List NFC chips
- `account`: Balance and free links
- `top_up`: Top up the balance
- `request_feature`: Ask for a feature
- `vote_feature`: Vote for a feature
- `list_feature_requests`: Feature requests
- `send_feedback`: Send feedback
- `whats_new`: What's new

Each tool makes the same API call with your key, so prices, scopes, checks and limits are the same as above
(US$0.01 a new link from the balance, 25 free with a verified email), and the link's history shows the change as
`mcp:<your assistant>`. At most 120 tool calls a minute per key. Signing in from claude.ai or ChatGPT without
pasting a key comes later.

Step by step, with VS Code keeping the key out of its file: [Connect an AI assistant](https://fwdr.link/guides/connect-ai-assistant).

## QR codes and NFC chips

- `GET /v1/qr/{slug}?channel=q&format=svg` returns the link's QR code (`format=png` for an image, `size` for its
  width in pixels from 128 to 2048, `ecc` L, M, Q or H, `point` for a named sub-code). The headers `X-QR-Text` and `X-QR-Modules` say what it holds and how big it is.
- `POST /v1/nfc-tags` with `{"uid": "04A2...", "link": "<slug>", "label": "...", "params": {"loc": "desk"}}` registers a
  chip on one of your links; its taps are counted per chip and its variables are passed on. `GET /v1/nfc-tags` lists
  them, `PATCH /v1/nfc-tags/{uid}` changes one.
- A QR code for any other address or text, with no key: `GET /v1/qr-code?data=...` (SVG or PNG; `POST` with JSON adds a
  logo). In a browser: the [free QR code generator](https://fwdr.link/qr-code-generator).

## Keys with limits

`POST /v1/keys` with `{"label": "...", "scopes": ["links:read", "stats:read"], "domains": ["fwdr.link"]}` makes another
key for the same account, shown once. Scopes: `links:read`, `links:write`, `stats:read`, `tags:write`, `billing`,
`keys`. A key without scopes can do everything; a key can only hand out what it has itself. `GET /v1/keys` lists the
account's keys (never the keys themselves), `DELETE /v1/keys/{id}` revokes one.

A daily spending limit: `"max_spend_usd_per_day": 5` (US$) on `POST /v1/keys`, or later with
`PATCH /v1/keys/{id}` (`null` for none). Links the key pays for since 00:00 UTC can't cost more: the one that would
answers `402` with code `daily_limit` and `resets_at`. Free links count as nothing. A key with a limit can only
hand out the same limit or a lower one. People set it on the Keys page of the dashboard.

## Your own domain

A customer's own domain is set up by hand for now: write to hello@fwdr.link. Its links are made and changed with the
same `/v1` calls at `https://fwdr.link`, naming links `domain/slug` (`links.example.com/spring`). A slug is required, targets must be `https://`,
and a link may have a `fallback` for when it is switched off. `GET /v1/domains` lists your domains.

Some domains check a new target before it goes live. There `PATCH` with a new `target` (and optional `go_live_at`)
answers `202` with the link as it is live and `pending: {id, status, target, go_live_at, message}`; a target on one of
the domain's trusted hosts goes live at once. A new link starts at its fallback until its target is checked.
`GET /v1/links/{domain}/{slug}` shows `pending` and `last_change`, `DELETE /v1/links/{domain}/{slug}/pending`
withdraws a waiting change, and `GET /v1/changes?status=&domain=` lists your changes.

## Paying

| | |
|---|---|
| Prepaid | US$0.01 a link from your balance (after the free links). `GET /v1/account` shows balance and free links left; `GET /v1/account/ledger` every charge. No balance: HTTP 402 with how to top up. |
| Top up with crypto | `POST /v1/topups` with `{"amount_usd": 10, "pay_with": "usdc-base", "refund_to": "<your address>"}`, from US$1. USDC, USDT, NEAR and more on several chains (`GET /v1/topups/assets`). |
| Top up by card | Coming. `POST /v1/topups/card` with `{"amount_usd": 25}` returns a Stripe page for a person to pay, from US$10. It never charges by itself. |

All prices: [https://fwdr.link/pricing](https://fwdr.link/pricing), or as JSON at `https://fwdr.link/.well-known/pricing`.

## Errors

Every error is JSON: `{"error": "what went wrong and how to fix it"}`. Many also carry a `code`
(`no_such_link`, `slug_taken`, `bad_slug`, `not_your_domain`, `missing_scope`, `needs_fallback`, …); act on
the code, show the sentence. `400` bad input or too many requests, `401` missing or wrong key, `402` no balance
(code `payment_required`), a key's daily spending limit reached (`daily_limit`) or payment needed, `403` not open
yet or not allowed, `404` nothing to withdraw or no such key, `409` the same Idempotency-Key is still running or was
used for a different request, `429` too much feedback, `503` not set up on this server.

## Link format

`https://fwdr.link/<slug>[/<channel>][/<point>][?variables]`. Channels: `q` QR, `n` NFC, `c` card, `p` packaging, `f` flyer,
`e` email, `s` social. Redirects are 302 (never cached), with UTM tags added unless the target sets its own.

## For agents and tools

- Plain-text guide: [https://fwdr.link/llms.txt](https://fwdr.link/llms.txt)
- OpenAPI: [https://fwdr.link/openapi.json](https://fwdr.link/openapi.json)
- Prices as JSON: [https://fwdr.link/.well-known/pricing](https://fwdr.link/.well-known/pricing)
- Ask for a feature: `POST /v1/feature-requests` with `{"title": "...", "description": "...", "use_case": "..."}`
- Tell us how it went: `POST /v1/feedback` with `{"rating": 5, "text": "..."}` (key optional)
- Report abuse: `POST /v1/abuse` with `{"url": "...", "reason": "..."}`
- What changed lately: `GET /v1/changelog` (no key, free)

## What's new

Every change you can notice is on [https://fwdr.link/changelog](https://fwdr.link/changelog), newest first. Follow it with the Atom feed
[https://fwdr.link/changelog.xml](https://fwdr.link/changelog.xml), or ask the API: `GET https://fwdr.link/v1/changelog` answers the same list as
JSON, with no key and no charge. Optional: `since` (a day, YYYY-MM-DD), `tag` (one tag, for example `api`, `mcp` or
`pricing`; all of them in the OpenAPI document) and `limit` (1 to 100, default 20). A bad value answers `400` with
`bad_since`, `bad_tag` or `bad_limit`.

## Questions

### How do I try the fwdr API without signing up?
Create a test key with `POST https://fwdr.link/v1/accounts/test`. It works with the whole API; test links show a preview page instead of forwarding and expire after 24 hours.

### How do I change where a short link goes?
Send `PATCH /v1/links/{slug}` with the new `target`. The short link and its QR code stay the same.

### What does the count include?
Opens by people, by day, channel, country, city, device and operating system. Bots and link previews are counted separately, and visitors' IP addresses are not stored.

### Which key do I use for a test link's count?
The same test key that created it, with the slug from the answer: `GET /v1/stats/t/{slug}`.

### Is it safe to send the same request twice?
Yes, with an `Idempotency-Key` header on `POST /v1/links`: the same request again answers with the link the first one made and charges nothing. The same key with a different request is refused with `409` and `idempotency_conflict`.

_Updated 21 November 2026. fwdr.link is run by Bonzer Boys Studio, Australia._
