Calls for Solo, Team, and Agency.

Key

Every call starts at /api/v1. Send the key from Account as X-API-Key, or as Bearer. A sample key is shown below. Your real key stays on Account.

X-API-Key: your-key
Authorization: Bearer your-key

A login that can only view can read links, clicks, and names. It cannot create or change them. A QR code and a campaign address do not save a link, so those two calls stay open.

Rate limits

Solo is 60 calls a minute and 600 an hour. Team is 300 a minute and 3,000 an hour. Agency is 600 a minute and 6,000 an hour. Admin is not limited. Under the limit, the response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the cap you will hit first. Over the limit, the response is 429 and includes Retry-After.

v1 stability

Changes to /api/v1 are additive only: new fields, new endpoints. Breaking changes get a new version and 6 months' notice before v1 is retired.

Workspace

Leave workspace off and the call uses your own links. On Agency, GET /api/v1/account lists the workspaces this login can open. Send that id as workspace on the address or in the call. A workspace this login cannot open is refused.

GET /api/v1/links?workspace=12

List links

GET /api/v1/links returns your links, including click_count, last_clicked_at, and has_password. Add q to search. status can be active or disabled.

GET /api/v1/links?q=summer&status=active

Read one link

GET /api/v1/links/summer returns that link. A prefix is part of the path, as in GET /api/v1/links/acme/summer.

Create a link

POST /api/v1/links needs long_url. slug sets your own ending (letters, numbers, dashes). Leave it out and one is made for you. title names the link on Account. A taken ending returns 409. A bad or reserved ending returns 400. On Team and Agency, password sets a password before the link opens. Use 4 to 72 characters. Leave password out to create the link without one.

POST /api/v1/links
{"long_url":"https://example.com/offer","slug":"summer","title":"Summer offer"}

Change a link

PATCH /api/v1/links/15 uses the numeric id. Send only the fields you want to change. Leave password out to keep the current one. A value sets a new one. An empty value removes it.

PATCH /api/v1/links/15
{"password":""}

Clicks

GET /api/v1/links/15/clicks returns the newest 100 clicks in the window. Each row has the time, referrer, device, browser, and operating system. summary groups those same facts. days is 7, 30, or 90. Anything else uses 30.

GET /api/v1/links/15/clicks?days=30

Stats

GET /api/v1/links/15/stats returns total_clicks, by_day counts, and top_referrers. Use from and to as dates, or days as 7, 30, or 90.

GET /api/v1/links/15/stats?days=30

Names

GET /api/v1/domains returns each name on this workspace, whether it is verified, whether it is ready, and the four page fields. PATCH /api/v1/domains/4 changes only the page fields you send. A view-only login can read, not write.

PATCH /api/v1/domains/4
{"home_title":"Welcome","home_body":"Pick a link.","missing_title":"Not a link","missing_body":"That path is not a short link."}

QR code

GET /api/v1/qr?slug=summer returns the image. format is png or svg. Send url instead of slug when the code is not for a saved link.

GET /api/v1/qr?slug=summer&format=png

Campaign address

POST /api/v1/campaign-url returns tagged_url. It does not save a link.

POST /api/v1/campaign-url
{"website_url":"https://example.com","utm_source":"print"}

Prefix

POST /api/v1/clients adds a prefix for endings such as acme/summer. An Agency client workspace is chosen with workspace, not this call.

POST /api/v1/clients
{"slug":"acme","name":"Acme"}

Account

GET /api/v1/account returns this login and the workspaces it can open. is_own is true for your workspace.

GET /api/v1/account

Pricing · FAQ · Account