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.
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
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 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
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"}'
{"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
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
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:
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):
{
"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:
{ "servers": { "fwdr": { "type": "http", "url": "https://fwdr.link/mcp", "headers": { "Authorization": "Bearer <your key>" } } } }
The tools:
create_link: Make a short linkupdate_link: Change a linkget_link: Show a linklist_links: List linksswitch_link_off: Switch a link offswitch_link_on: Switch a link onlink_stats: Link numberslink_history: Link historyqr_code: QR coderegister_nfc_tag: Register an NFC chiplist_nfc_tags: List NFC chipsaccount: Balance and free linkstop_up: Top up the balancerequest_feature: Ask for a featurevote_feature: Vote for a featurelist_feature_requests: Feature requestssend_feedback: Send feedback
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.
QR codes and NFC chips
GET /v1/qr/{slug}?channel=q&format=svgreturns the link's QR code (format=pngfor an image,sizefor its width in pixels from 128 to 2048,eccL, M, Q or H,pointfor a named sub-code). The headersX-QR-TextandX-QR-Modulessay what it holds and how big it is.POST /v1/nfc-tagswith{"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-tagslists 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;POSTwith JSON adds a logo). In a browser: the free 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, 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
- OpenAPI: https://fwdr.link/openapi.json
- Prices as JSON: https://fwdr.link/.well-known/pricing
- Ask for a feature:
POST /v1/feature-requestswith{"title": "...", "description": "...", "use_case": "..."} - Tell us how it went:
POST /v1/feedbackwith{"rating": 5, "text": "..."}(key optional) - Report abuse:
POST /v1/abusewith{"url": "...", "reason": "..."}
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.