{"openapi":"3.1.0","info":{"title":"fwdr.link: URL shortener API for AI agents","version":"1.1.0","summary":"Create short links, change where they go and read how often they were opened.","description":"Free test keys (test links show a preview instead of forwarding and expire after 24 hours). Live links US$0.01 each from a prepaid balance; pay as you go 0.01 USDC per link with x402. Errors are JSON {\"error\": \"...\", \"code\": \"...\"}; code is there on many errors. Prices: https://fwdr.link/.well-known/pricing. Guide: https://fwdr.link/docs.","contact":{"email":"hello@fwdr.link","url":"https://fwdr.link/docs"},"termsOfService":"https://fwdr.link/terms"},"servers":[{"url":"https://fwdr.link"}],"externalDocs":{"url":"https://fwdr.link/docs","description":"Quickstart"},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A fwdr_... or fwdr_test_... key. Keys may be limited to scopes (links:read links:write stats:read tags:write billing keys) and domains; a key without scopes can make every call."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong and how to fix it."},"code":{"type":"string","description":"A short stable name, e.g. no_such_link, slug_taken, missing_scope."}},"required":["error"]},"LinkInput":{"type":"object","properties":{"target":{"type":"string","format":"uri","description":"Where the link forwards to (https or http; https on your own domain). May hold placeholders like {loc}."},"static_params":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables always added to the target, e.g. {\"ref\": \"agent\"}."},"allowed_params":{"type":"array","description":"Variables a visitor's link may pass on; all others are dropped.","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["text","slug","number","enum"],"default":"text"},"values":{"type":"array","items":{"type":"string"},"description":"For kind enum."},"max":{"type":"integer","maximum":200,"description":"Longest value (default 100)."},"as":{"type":"string","description":"Pass the value on under this name."}},"required":["name"]}},"utm":{"type":"boolean","default":true,"description":"Add UTM tags unless the target has its own."},"forward_geo":{"type":"boolean","default":false,"description":"Allow {country} {region} {city} in the target."},"forward_tag":{"type":"boolean","default":true,"description":"Pass an NFC chip's UID on as tag=<UID>."},"tags":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"fallback":{"type":"string","description":"Your own domain only: where the link goes while it is switched off or its target waits for checks."},"slug":{"type":"string","description":"Your own slug (live keys only; required on your own domain), or domain/slug. Leave out for a random one."},"domain":{"type":"string","description":"One of your own domains; default fwdr.link."}},"required":["target"]},"Link":{"type":"object","properties":{"url":{"type":"string","description":"The short link."},"qr_url":{"type":"string","description":"Upper-case address for a compact QR code."},"nfc_url":{"type":"string"},"domain":{"type":"string"},"slug":{"type":"string"},"target":{"type":"string"},"fallback":{"type":["string","null"],"description":"Your own domain only."},"active":{"type":"boolean"},"check":{"type":"string","description":"Safety check: \"safety check running (a few seconds)\", safe, held, malicious or skipped. While it runs nobody is sent to the unjudged target."},"serving":{"type":"string","description":"Only while a changed target is being checked: the previous judged target, where people are sent right now."},"check_reason":{"type":"string"},"mode":{"type":"string","enum":["test"],"description":"Present on test links."},"expires_at":{"type":"string","format":"date-time","description":"Test links only."},"utm":{"type":"boolean"},"static_params":{"type":"object"},"allowed_params":{"type":"array"},"forward_geo":{"type":"boolean"},"forward_tag":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"charged":{"type":"string","description":"What a create call cost, e.g. \"US$0.01\", \"1 free link\", \"nothing (test mode)\"."},"existing":{"type":"boolean","description":"A repeat (Idempotency-Key, or the same slug and target on your own domain): nothing was charged."},"pending":{"type":["object","null"],"properties":{"id":{"type":"integer"},"status":{"type":"string","description":"checking, scheduled, review, live, rejected or withdrawn."},"target":{"type":"string"},"go_live_at":{"type":["string","null"],"format":"date-time"},"message":{"type":"string"}},"description":"A new target waiting for its checks (domains that check first)."},"last_change":{"type":["object","null"],"description":"Your own domain: how the last change ended (status, target, comment, decided_at)."}}},"Pending":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","description":"checking, scheduled, review, live, rejected or withdrawn."},"target":{"type":"string"},"go_live_at":{"type":["string","null"],"format":"date-time"},"message":{"type":"string"}}},"Change":{"type":"object","properties":{"id":{"type":"string","description":"<date>-<slug>: unique, never changes. Also the anchor on the page."},"date":{"type":"string","format":"date","description":"The day it reached production (UTC)."},"kind":{"type":"string","enum":["new","improved","changed","fixed"],"description":"changed: something you may need to act on."},"title":{"type":"string"},"summary":{"type":"string","description":"Plain text, at most 400 characters."},"tags":{"type":"array","items":{"type":"string","enum":["api","mcp","dashboard","payments","pricing","qr","domains","website","reliability"]}},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"}},"required":["label","url"]}},"url":{"type":"string","format":"uri","description":"The entry on the page."}},"required":["id","date","kind","title","summary","tags","links","url"]}}},"paths":{"/v1/accounts/test":{"post":{"operationId":"createTestKey","summary":"Get a free test key (no signup)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"}}},"example":{"label":"my agent"}}}},"responses":{"201":{"description":"Test key","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"Shown once. Keep it secret."}}}}}},"400":{"description":"Too many test accounts from here today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signup":{"post":{"operationId":"startSignup","summary":"Email a 6-digit code for a live key","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"ref":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional `ref`: where you heard about fwdr (a word, for example the site or tool). It only helps us learn what works. Also taken from the query string; a value that doesn't fit is ignored."},"utm_source":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."},"utm_medium":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."},"utm_campaign":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."}},"required":["email"]}}}},"responses":{"200":{"description":"Code sent"},"400":{"description":"Bad email or too many codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sign-up is not open yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/signup/verify":{"post":{"operationId":"verifySignup","summary":"Exchange the code for a live key and 25 free links","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"code":{"type":"string"},"label":{"type":"string"},"ref":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional `ref`: where you heard about fwdr (a word, for example the site or tool). It only helps us learn what works. Also taken from the query string; a value that doesn't fit is ignored."},"utm_source":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."},"utm_medium":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."},"utm_campaign":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."}},"required":["email","code"]}}}},"responses":{"201":{"description":"Live key","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"Shown once. Keep it secret."}}}}}},"400":{"description":"Wrong or old code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sign-up is not open yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Sign-up is at today's limit of new accounts (code signup_busy). Try again tomorrow, or write to hello@fwdr.link. Signing in with an email that already has an account still works.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/accounts":{"post":{"operationId":"createAccount","summary":"A live key without an email (no free links: top up before the first link)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"ref":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional `ref`: where you heard about fwdr (a word, for example the site or tool). It only helps us learn what works. Also taken from the query string; a value that doesn't fit is ignored."},"utm_source":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."},"utm_medium":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."},"utm_campaign":{"type":"string","maxLength":60,"pattern":"^[a-z0-9._-]+$","description":"Optional, as ref."}}}}}},"responses":{"201":{"description":"Live key","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"Shown once. Keep it secret."}}}}}},"400":{"description":"Too many new accounts from here today.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Sign-up is not open yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Sign-up is at today's limit of new accounts (code signup_busy). Try again tomorrow, or write to hello@fwdr.link. Signing in with an email that already has an account still works.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/account":{"get":{"operationId":"getAccount","summary":"Balance and free links left","responses":{"200":{"description":"Account"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]},"patch":{"operationId":"updateAccount","summary":"Details for invoices (not for test keys)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"2-letter code; decides GST."},"business_name":{"type":"string"},"tax_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Account"},"400":{"description":"Bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]}},"/v1/account/ledger":{"get":{"operationId":"getLedger","summary":"Every charge and top-up","parameters":[{"name":"limit","in":"query","required":false,"description":"At most this many rows.","schema":{"type":"integer"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Ledger"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}]}},"/v1/links":{"post":{"operationId":"createLink","summary":"Create a short link (US$0.01 from the balance, free with a test key)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"1 to 100 visible characters, remembered for 7 days. The same key with the same request answers 200 with the link it made and charges nothing; with a different request it answers 409 idempotency_conflict.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkInput"},"example":{"target":"https://example.com/welcome"}}}},"responses":{"200":{"description":"A repeat: the link made before, nothing charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"201":{"description":"The link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"202":{"description":"Your own domain, checks first: the link is live at its fallback and the target is pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"Bad input, unsafe target or slug taken.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No free links or balance left: top up (code payment_required); or this key's daily spending limit is reached (code daily_limit, with resets_at).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This Idempotency-Key is still running (code idempotency_busy) or was used for a different request (code idempotency_conflict).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:write.","security":[{"bearer":[]}]},"get":{"operationId":"listLinks","summary":"Your links with scan counts","parameters":[{"name":"tag","in":"query","required":false,"description":"Only links with this tag.","schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"description":"One of your domains (default fwdr.link).","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Links"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:read.","security":[{"bearer":[]}]}},"/v1/links/{link}":{"get":{"operationId":"getLink","summary":"One link (on your own domain also pending and last_change)","parameters":[{"name":"link","in":"path","required":true,"description":"The link: its slug on fwdr.link (q7xkm2p, t/q7xkm2p for a test link), or domain/slug on your own domain (links.example.com/spring). The / may stay unencoded.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"The link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"No such link in your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:read.","security":[{"bearer":[]}]},"patch":{"operationId":"updateLink","summary":"Change a link; only the fields sent change","description":"A new target is checked before anyone is sent there; until then people go to the previous judged target, shown as serving. On a domain that checks first, a new target waits for its checks: 202 with pending. A key with scopes needs links:write.","parameters":[{"name":"link","in":"path","required":true,"description":"The link: its slug on fwdr.link (q7xkm2p, t/q7xkm2p for a test link), or domain/slug on your own domain (links.example.com/spring). The / may stay unencoded.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","format":"uri","description":"Where the link forwards to (https or http; https on your own domain). May hold placeholders like {loc}."},"static_params":{"type":"object","additionalProperties":{"type":"string"},"description":"Variables always added to the target, e.g. {\"ref\": \"agent\"}."},"allowed_params":{"type":"array","description":"Variables a visitor's link may pass on; all others are dropped.","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["text","slug","number","enum"],"default":"text"},"values":{"type":"array","items":{"type":"string"},"description":"For kind enum."},"max":{"type":"integer","maximum":200,"description":"Longest value (default 100)."},"as":{"type":"string","description":"Pass the value on under this name."}},"required":["name"]}},"utm":{"type":"boolean","default":true,"description":"Add UTM tags unless the target has its own."},"forward_geo":{"type":"boolean","default":false,"description":"Allow {country} {region} {city} in the target."},"forward_tag":{"type":"boolean","default":true,"description":"Pass an NFC chip's UID on as tag=<UID>."},"tags":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"fallback":{"type":"string","description":"Your own domain only: where the link goes while it is switched off or its target waits for checks."},"active":{"type":"boolean","description":"false switches the link off, true on again."},"go_live_at":{"type":"string","format":"date-time","description":"Domains that check first: when the new target goes live."}}},"example":{"target":"https://example.com/new-page"}}}},"responses":{"200":{"description":"The link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"202":{"description":"The link as it is live, with the new target pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"Bad input or no such link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}]},"delete":{"operationId":"switchOffLink","summary":"Switch a link off (links are never deleted)","parameters":[{"name":"link","in":"path","required":true,"description":"The link: its slug on fwdr.link (q7xkm2p, t/q7xkm2p for a test link), or domain/slug on your own domain (links.example.com/spring). The / may stay unencoded.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"The link, inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"No such link in your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:write.","security":[{"bearer":[]}]}},"/v1/links/{link}/pending":{"delete":{"operationId":"withdrawPendingChange","summary":"Withdraw a new target that waits for its checks","parameters":[{"name":"link","in":"path","required":true,"description":"The link: its slug on fwdr.link (q7xkm2p, t/q7xkm2p for a test link), or domain/slug on your own domain (links.example.com/spring). The / may stay unencoded.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"The link, with withdrawn"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No pending change (code no_pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:write.","security":[{"bearer":[]}]}},"/v1/stats/{link}":{"get":{"operationId":"getLinkStats","summary":"How often a link was opened: totals, by day, channel, point, place, device, variable and NFC chip","parameters":[{"name":"link","in":"path","required":true,"description":"The link: its slug on fwdr.link (q7xkm2p, t/q7xkm2p for a test link), or domain/slug on your own domain (links.example.com/spring). The / may stay unencoded.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Look back this many days (default 30).","schema":{"type":"integer","default":30}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Counts. No IP addresses are stored.","content":{"application/json":{"schema":{"type":"object","properties":{"scans":{"type":"integer","description":"Opens by people."},"people":{"type":"integer","description":"Different visitors (a daily id)."},"bots_and_previews":{"type":"integer","description":"Crawlers and chat apps unfurling the link; not in scans."},"first_scan":{"type":["string","null"]},"last_scan":{"type":["string","null"]},"by_day":{"type":"array"},"by_channel":{"type":"array"},"by_point":{"type":"array"},"by_country":{"type":"array"},"by_city":{"type":"array"},"by_device":{"type":"array"},"by_os":{"type":"array"},"by_param":{"type":"array"},"nfc_tags":{"type":"array"}}}}}},"400":{"description":"No such link in your account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs stats:read.","security":[{"bearer":[]}]}},"/v1/history/{link}":{"get":{"operationId":"getLinkHistory","summary":"Every change to a link: when, by whom, before and after","parameters":[{"name":"link","in":"path","required":true,"description":"The link: its slug on fwdr.link (q7xkm2p, t/q7xkm2p for a test link), or domain/slug on your own domain (links.example.com/spring). The / may stay unencoded.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"At most this many rows.","schema":{"type":"integer"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Changes, newest first"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:read.","security":[{"bearer":[]}]}},"/v1/qr/{link}":{"get":{"operationId":"getQrCode","summary":"The link's QR code (SVG or PNG)","parameters":[{"name":"link","in":"path","required":true,"description":"The link: its slug on fwdr.link (q7xkm2p, t/q7xkm2p for a test link), or domain/slug on your own domain (links.example.com/spring). The / may stay unencoded.","schema":{"type":"string"}},{"name":"channel","in":"query","required":false,"description":"Channel letter in the code (default q).","schema":{"type":"string"}},{"name":"point","in":"query","required":false,"description":"A named sub-code.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"svg (default) or png.","schema":{"type":"string","enum":["svg","png"]}},{"name":"ecc","in":"query","required":false,"description":"Error correction (default M).","schema":{"type":"string","enum":["L","M","Q","H"]}},{"name":"size","in":"query","required":false,"description":"PNG only: its width in pixels (default 20 pixels a module).","schema":{"type":"integer","minimum":128,"maximum":2048}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"The code; headers X-QR-Text and X-QR-Modules say what it holds and how big it is.","content":{"image/svg+xml":{},"image/png":{}}},"400":{"description":"Bad channel, point or size (code bad_size).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:read.","security":[{"bearer":[]}]}},"/v1/nfc-tags":{"get":{"operationId":"listNfcTags","summary":"NFC chips on your links","parameters":[{"name":"link","in":"query","required":false,"description":"Only chips on this link.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Chips"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:read.","security":[{"bearer":[]}]},"post":{"operationId":"registerNfcTag","summary":"Register a chip on one of your links: taps are counted per chip and its variables passed on","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"uid":{"type":"string","description":"The chip's UID (hex)."},"link":{"type":"string"},"label":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}}},"required":["uid","link"]}}}},"responses":{"201":{"description":"The chip"},"400":{"description":"Bad input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs tags:write.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]}},"/v1/nfc-tags/{uid}":{"patch":{"operationId":"updateNfcTag","summary":"Change a chip's link, label or variables","parameters":[{"name":"uid","in":"path","required":true,"description":"The chip's UID.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"link":{"type":"string"},"label":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"The chip"},"400":{"description":"Bad input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs tags:write.","security":[{"bearer":[]}]}},"/v1/domains":{"get":{"operationId":"listDomains","summary":"Your own domains (fwdr.link is everyone's and isn't listed)","responses":{"200":{"description":"Domains"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:read.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]}},"/v1/changes":{"get":{"operationId":"listChanges","summary":"New targets waiting or decided on your domains that check first, newest first","parameters":[{"name":"status","in":"query","required":false,"description":"checking, scheduled, review, live, rejected or withdrawn.","schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"description":"One of your domains.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Changes"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs links:read.","security":[{"bearer":[]}]}},"/v1/keys":{"get":{"operationId":"listKeys","summary":"The account's keys (prefix, label, scopes, domains, daily spending limit; never the key)","responses":{"200":{"description":"Keys"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs keys.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]},"post":{"operationId":"createKey","summary":"Another key for the same account, with the same scopes, domains and daily spending limit or fewer","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"scopes":{"type":["array","null"],"items":{"type":"string","enum":["links:read","links:write","stats:read","tags:write","billing","keys"]}},"domains":{"type":["array","null"],"items":{"type":"string"}},"max_spend_usd_per_day":{"type":["number","null"],"minimum":0,"maximum":10000,"description":"Daily spending limit in US$ for links paid with this key (null: none). Its charges since 00:00 UTC may not pass it: a link that would answers 402 with code daily_limit and resets_at. Free links count as 0. Left out on a new key: the same as the key making it. A key with a limit can't give a higher one, or none."}}}}}},"responses":{"201":{"description":"The new key, shown once","content":{"application/json":{"schema":{"type":"object","properties":{"api_key":{"type":"string","description":"Shown once. Keep it secret."}}}}}},"400":{"description":"Bad scopes, domains or limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs keys.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]}},"/v1/keys/{id}":{"patch":{"operationId":"updateKey","summary":"Change a key's label or daily spending limit","parameters":[{"name":"id","in":"path","required":true,"description":"The key's id.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":["string","null"]},"max_spend_usd_per_day":{"type":["number","null"],"minimum":0,"maximum":10000,"description":"Daily spending limit in US$ for links paid with this key (null: none). Its charges since 00:00 UTC may not pass it: a link that would answers 402 with code daily_limit and resets_at. Free links count as 0. Left out on a new key: the same as the key making it. A key with a limit can't give a higher one, or none."}}}}}},"responses":{"200":{"description":"The key (never the key itself)"},"400":{"description":"Bad limit (code bad_limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such key (code no_such_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs keys.","security":[{"bearer":[]}]},"delete":{"operationId":"revokeKey","summary":"Revoke a key","parameters":[{"name":"id","in":"path","required":true,"description":"The key's id.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such key (code no_such_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs keys.","security":[{"bearer":[]}]}},"/v1/topups":{"post":{"operationId":"createTopup","summary":"Top up with crypto (USDC and more, through NEAR Intents); answers where to send what","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount_usd":{"type":"number","minimum":1},"pay_with":{"type":"string","description":"e.g. usdc-base, usdc-sol, usdc-near, usdt-eth, near"},"refund_to":{"type":"string"}},"required":["amount_usd","pay_with","refund_to"]}}}},"responses":{"201":{"description":"Deposit instructions"},"400":{"description":"Bad amount or coin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]}},"/v1/topups/assets":{"get":{"operationId":"listTopupAssets","summary":"Coins you can top up with","responses":{"200":{"description":"Coins and aliases"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]}},"/v1/topups/{id}":{"get":{"operationId":"getTopup","summary":"Top-up status","parameters":[{"name":"id","in":"path","required":true,"description":"The top-up's id.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Status"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}]}},"/v1/topups/card":{"post":{"operationId":"createCardTopup","summary":"A Stripe page for a person to top up by card (from US$10); never charges by itself","description":"Answers checkout_url. Not set up on this server yet: answers 503. A key with scopes needs billing.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount_usd":{"type":"number","minimum":10}},"required":["amount_usd"]}}}},"responses":{"201":{"description":"checkout_url"},"400":{"description":"Bad amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Cards are not set up on this server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]},"get":{"operationId":"listCardTopups","summary":"Your card top-ups","responses":{"200":{"description":"Card top-ups"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}],"parameters":[{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}]}},"/v1/topups/card/{id}":{"get":{"operationId":"getCardTopup","summary":"One card top-up","parameters":[{"name":"id","in":"path","required":true,"description":"The card top-up's id.","schema":{"type":"string"}},{"name":"X-Fwdr-Actor","in":"header","required":false,"description":"Who of your people or systems made this call (1 to 64 letters, digits, :, _ or -). The link history keeps it as <account>/<actor>.","schema":{"type":"string"}}],"responses":{"200":{"description":"Status"},"401":{"description":"Missing or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Not allowed for this key (code missing_scope, not_your_domain, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A key with scopes needs billing.","security":[{"bearer":[]}]}},"/v1/pay/links":{"get":{"operationId":"getPayAsYouGoPrice","summary":"What a link costs without an account, and how to pay (never takes a payment)","description":"Answers 402 with the same PAYMENT-REQUIRED header (x402 v2) an unpaid POST gets, Allow: POST, and how to pay: send POST /v1/pay/links with {\"target\": \"https://…\"} and the payment. HEAD answers the same without a body. A GET that carries a payment header answers 405: payments are taken by POST only.","responses":{"402":{"description":"How to pay (code use_post); the PAYMENT-REQUIRED header names the price and where to pay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Pay as you go is not open yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"A payment was sent with GET; send it with POST (code use_post).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createLinkPayAsYouGo","summary":"Create a link without an account, paid per request with x402 (0.01 USDC on Base)","description":"The first call answers 402 with a PAYMENT-REQUIRED header (x402 v2). Pay with any x402 client and repeat with PAYMENT-SIGNATURE. 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.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"slug":{"type":"string"},"static_params":{"type":"object","additionalProperties":{"type":"string"}}},"required":["target"]},"example":{"target":"https://example.com/a/long/page"}}}},"responses":{"200":{"description":"The link this payment already bought (existing: true); nothing charged again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"201":{"description":"The link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"400":{"description":"Bad input or unsafe target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402): the PAYMENT-REQUIRED header names the price and where to pay"},"403":{"description":"Pay as you go is not open yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This payment's link is made and the payment is still settling (code payment_busy); send it again after Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pay/receipts/{tx}":{"get":{"operationId":"getPayReceipt","summary":"A settled pay-as-you-go payment by its transaction hash (no key)","description":"Network, amount, the short link and when it was made; never the target. 60 lookups a minute and 1,000 a day from one address.","parameters":[{"name":"tx","in":"path","required":true,"description":"The transaction hash: 0x… on Base, base58 on NEAR.","schema":{"type":"string"}}],"responses":{"200":{"description":"The payment","content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"string","description":"CAIP-2, e.g. eip155:8453 or near:mainnet"},"amount_usd":{"type":"number"},"url":{"type":"string"},"made_at":{"type":"string","format":"date-time"}},"required":["network","amount_usd","url","made_at"]}}}},"404":{"description":"No settled payment with this transaction (code no_such_payment).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many lookups from here (code too_many); the Retry-After header says how many seconds to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/qr-code":{"get":{"operationId":"makeQrCode","summary":"A free static QR code for any address or text (no key)","description":"The code holds exactly the data given: it doesn't go through fwdr, never expires and has no watermark, and nothing about the call is stored. An http(s) address with an IP address as host, a user name or password, or a blocked domain is refused. 60 calls a minute and 1,000 a day from one address.","parameters":[{"name":"data","in":"query","required":true,"description":"The address or text, 1 to 1,000 characters.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"svg (default) or png.","schema":{"type":"string","enum":["svg","png"],"default":"svg"}},{"name":"size","in":"query","required":false,"description":"Width and height in pixels. A PNG needs at least 2 pixels a module.","schema":{"type":"integer","minimum":128,"maximum":2048,"default":512}},{"name":"margin","in":"query","required":false,"description":"Quiet zone in modules.","schema":{"type":"integer","minimum":0,"maximum":8,"default":4}},{"name":"fg","in":"query","required":false,"description":"Module colour, #rrggbb (send # as %23 in a query). Must be darker than bg, contrast at least 4.5 to 1.","schema":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","default":"#000000"}},{"name":"bg","in":"query","required":false,"description":"Background colour, #rrggbb.","schema":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","default":"#ffffff"}},{"name":"ecc","in":"query","required":false,"description":"Error correction; always H with a logo or logo_space.","schema":{"type":"string","enum":["L","M","Q","H"],"default":"M"}},{"name":"logo_space","in":"query","required":false,"description":"true: leave a clear square in the middle for a logo you add yourself (ecc becomes H and the code is at least 37 modules a side).","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The code. Headers: X-QR-Modules (modules a side, without the margin), X-QR-Ecc, and with a clear square X-QR-Logo-Box (where a logo goes: x y width height, in pixels for PNG, in the SVG's own units for SVG).","content":{"image/svg+xml":{},"image/png":{}}},"400":{"description":"Bad input (code bad_data, too_long, bad_format, bad_size, bad_margin, bad_color, low_contrast, bad_ecc, bad_logo, logo_too_big, logo_type_mismatch, logo_needs_svg, size_too_small, ip_address, bad_target, blocked, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 calls a minute or 1,000 a day from here (code too_many); the Retry-After header says how many seconds to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"makeQrCodeWithLogo","summary":"A free static QR code, optionally with your logo in the middle (no key)","description":"The code holds exactly the data given: it doesn't go through fwdr, never expires and has no watermark, and nothing about the call is stored. An http(s) address with an IP address as host, a user name or password, or a blocked domain is refused. 60 calls a minute and 1,000 a day from one address. The logo is embedded as an image in the SVG (format svg only); it is used for this answer only and never fetched from an address.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","minLength":1,"maxLength":1000},"format":{"type":"string","enum":["svg","png"],"default":"svg","description":"svg (default) or png."},"size":{"type":"integer","minimum":128,"maximum":2048,"default":512,"description":"Width and height in pixels. A PNG needs at least 2 pixels a module."},"margin":{"type":"integer","minimum":0,"maximum":8,"default":4,"description":"Quiet zone in modules."},"fg":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","default":"#000000","description":"Module colour, #rrggbb (send # as %23 in a query). Must be darker than bg, contrast at least 4.5 to 1."},"bg":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","default":"#ffffff","description":"Background colour, #rrggbb."},"ecc":{"type":"string","enum":["L","M","Q","H"],"default":"M","description":"Error correction; always H with a logo or logo_space."},"logo_space":{"type":"boolean","default":false},"logo":{"type":"object","properties":{"type":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/svg+xml"]},"data":{"type":"string","contentEncoding":"base64","description":"At most 200 KB decoded; its first bytes must match type."}},"required":["type","data"]}},"required":["data"]},"example":{"data":"https://example.com","logo":{"type":"image/png","data":"iVBORw0KGgo..."}}}}},"responses":{"200":{"description":"The code. Headers: X-QR-Modules (modules a side, without the margin), X-QR-Ecc, and with a clear square X-QR-Logo-Box (where a logo goes: x y width height, in pixels for PNG, in the SVG's own units for SVG).","content":{"image/svg+xml":{},"image/png":{}}},"400":{"description":"Bad input (code bad_data, too_long, bad_format, bad_size, bad_margin, bad_color, low_contrast, bad_ecc, bad_logo, logo_too_big, logo_type_mismatch, logo_needs_svg, size_too_small, ip_address, bad_target, blocked, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request is bigger than 300 KB (code too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 60 calls a minute or 1,000 a day from here (code too_many); the Retry-After header says how many seconds to wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feature-requests":{"get":{"operationId":"listFeatureRequests","summary":"Feature requests, most votes first","parameters":[{"name":"status","in":"query","required":false,"description":"new, planned, building, shipped or declined.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"At most this many rows.","schema":{"type":"integer"}}],"responses":{"200":{"description":"List"}}},"post":{"operationId":"requestFeature","summary":"Ask for a feature (no key; 5 per hour)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"use_case":{"type":"string"},"example_call":{"type":"string"},"contact":{"type":"string","description":"Never shown publicly."}},"required":["title","description"]}}}},"responses":{"201":{"description":"Created, or the same request from you earlier"},"400":{"description":"Bad input or too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feature-requests/{id}":{"get":{"operationId":"getFeatureRequest","summary":"One feature request","parameters":[{"name":"id","in":"path","required":true,"description":"The request's id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"The request"},"400":{"description":"Bad id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/feature-requests/{id}/vote":{"post":{"operationId":"voteFeatureRequest","summary":"+1 a feature request (once per requester)","parameters":[{"name":"id","in":"path","required":true,"description":"The request's id.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Votes"}}}},"/v1/feedback":{"get":{"operationId":"listFeedback","summary":"Published feedback (only what senders allowed and we approved)","responses":{"200":{"description":"Feedback"}}},"post":{"operationId":"sendFeedback","summary":"Tell us how it went: a rating, a sentence, or both (key optional)","security":[{},{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rating":{"type":"integer","minimum":1,"maximum":5},"text":{"type":"string"},"name":{"type":"string"},"may_publish":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Received"},"400":{"description":"Neither a rating nor a text, or a bad value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A key was sent and it isn't valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too much feedback from here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/abuse":{"post":{"operationId":"reportAbuse","summary":"Report a harmful link (no key)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The fwdr link you're reporting."},"reason":{"type":"string"},"contact":{"type":"string"}},"required":["url"]}}}},"responses":{"201":{"description":"Received"},"400":{"description":"url is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/changelog":{"get":{"operationId":"getChangelog","summary":"What changed at fwdr.link, newest first (no key, free)","description":"New calls, tools, prices and fixes, written for customers. The same list as https://fwdr.link/changelog and the Atom feed https://fwdr.link/changelog.xml. Cached for 5 minutes (Cache-Control: public, max-age=300) with an ETag: send it back as If-None-Match and an unchanged list answers 304.","parameters":[{"name":"since","in":"query","required":false,"description":"Only entries dated on or after this day (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"tag","in":"query","required":false,"description":"Only entries with this tag.","schema":{"type":"string","enum":["api","mcp","dashboard","payments","pricing","qr","domains","website","reliability"]}},{"name":"limit","in":"query","required":false,"description":"At most this many entries.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"If-None-Match","in":"header","required":false,"description":"The ETag of an earlier answer.","schema":{"type":"string"}}],"responses":{"200":{"description":"The entries, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"string","format":"date","description":"The newest entry's date."},"entries":{"type":"array","items":{"$ref":"#/components/schemas/Change"}},"feed":{"type":"string","format":"uri","description":"The Atom feed."},"page":{"type":"string","format":"uri","description":"The page."}},"required":["updated","entries","feed","page"]}}}},"304":{"description":"Not changed since the ETag sent in If-None-Match."},"400":{"description":"Bad since, tag or limit (code bad_since, bad_tag or bad_limit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}