URL shortener API: create short links from code
Create and manage short links from your code: the base URL, your organisation code, an API key and its permissions, a first call, and what the API covers.
On this page
The Brevily API is a URL shortener API that lets your own code do what the console does with links: create them one at a time or a hundred at once, change and retire them, read their clicks, report sign-ups and sales, and set up webhooks. It's plain HTTPS and JSON, with one base URL per organisation and an API key that holds exactly the permissions you give it. This guide takes you from nothing to a working call in a few minutes.
Before you start: you need to be able to make API keys in your organisation. Keep two guides close: signing a request, to keep the secret off the network, and API errors, for every code a call can return.
How the Brevily URL shortener API works
Every call goes to the console's address, under /api and your organisation's code:
https://console.brevily.com/api/<ORG>/…- Your organisation's code is in Settings › General, under Code, with a copy button.
- JSON in, JSON out. Send bodies as JSON with
content-type: application/json, up to 1 MB. Any other body is refused with 415. - Every answer carries
x-request-id. Log it; support can find any request by it. - A key works in its own organisation only. Another organisation's code answers 404, never someone else's data.
[screenshot: Settings › General with the organisation Code and its copy button]
Create an API key with the right permissions
- Open Access › API keys and choose New key.
- Choose its Permissions. A key's permissions are the console's own: an area, such as Links or Integrations, with View, Edit, Create or Delete. For this guide, Links with View and Create is enough.
- Copy the key ID (
brv_ak_…) and the secret. The secret is shown once.
Give each integration its own key with the least it needs. A key never holds more than the person who makes it, and a call it isn't allowed to make answers 403 with the missing permission named in details.access. For the difference between organisation and personal keys, and the full steps, see signing a request.
Make your first API call
Keep the base URL and the key in shell variables, then create a link:
API=https://console.brevily.com/apiORG=EXAMPLE # Settings › General › CodeKEY=brv_ak_… # the key's IDSECRET=… # its secretcurl -X POST "$API/$ORG/links" \ -H "x-api-key: $KEY" \ -H "x-api-secret: $SECRET" \ -H "content-type: application/json" \ -d '{"url": "https://www.example.com/offers/spring", "domain": "go.example.com", "slug": "spring-sale", "title": "Spring newsletter, header button"}'Only url is required. Leave out domain and the link goes on your default domain; leave out slug and Brevily generates a back-half. The answer is 201 with the new link (trimmed here, with example values):
{ "id": "01J8ZQ4M2V7R5K3T9X6W1B0N4C", "domain": "go.example.com", "slug": "spring-sale", "shortUrl": "https://go.example.com/spring-sale", "title": "Spring newsletter, header button", "destination": "https://www.example.com/offers/spring", "state": "ACTIVE", "clicks": 0, "tags": [], "createdOn": "2026-11-11T15:42:57.563Z"}Keep the id: every other call about this link uses it. A link that can't be made answers 400, naming each field and what's wrong with it, such as a back-half that's taken.
The same call in Node
const { API, ORG, KEY, SECRET } = process.env;const res = await fetch(`${API}/${ORG}/links`, { method: 'POST', headers: { 'x-api-key': KEY, 'x-api-secret': SECRET, 'content-type': 'application/json', }, body: JSON.stringify({ url: 'https://www.example.com/offers/spring' }),});const link = await res.json();console.log(res.status, link.shortUrl);The same call in Python
import json, os, urllib.requestapi, org = os.environ["API"], os.environ["ORG"]req = urllib.request.Request( f"{api}/{org}/links", method="POST", data=json.dumps({"url": "https://www.example.com/offers/spring"}).encode(), headers={ "x-api-key": os.environ["KEY"], "x-api-secret": os.environ["SECRET"], "content-type": "application/json", },)with urllib.request.urlopen(req) as res: link = json.load(res) print(res.status, link["shortUrl"])These send the secret in a header on every call, inside HTTPS. To keep it off the network entirely, sign each request instead; see signing a request.
Read a link and its clicks
LINK=01J8ZQ4M2V7R5K3T9X6W1B0N4C # the id from the create callcurl "$API/$ORG/links/$LINK" -H "x-api-key: $KEY" -H "x-api-secret: $SECRET"curl "$API/$ORG/links/$LINK/stats" -H "x-api-key: $KEY" -H "x-api-secret: $SECRET"GET /links/{link}answers the link: where it goes (destination), what a visitor gets right now (state), its countedclicks, andstatsfor the last 30 days.GET /links/{link}/statsanswersclicks,visitorsandqrScansfor the range, the change on the range before, and a day-by-dayseries.
Clicks are counted the same way as in the console, with bots kept apart; see what Brevily counts as a click.
List links and page through them
A list answers a plain JSON array, one page at a time: 25 rows unless you ask for up to 100 with ?limit=, and the next page with ?page= (the first page is 1). Where you are comes back in three headers: x-total-rows, x-page-number and x-page-size.
const { API, ORG, KEY, SECRET } = process.env;const headers = { 'x-api-key': KEY, 'x-api-secret': SECRET };const links = [];for (let page = 1; ; page++) { const res = await fetch(`${API}/${ORG}/links?limit=100&page=${page}`, { headers }); const rows = await res.json(); links.push(...rows); const total = Number(res.headers.get('x-total-rows')); if (rows.length === 0 || links.length >= total) break;}console.log(`${links.length} links`);What the Brevily API covers
- Links: create one link or a list of up to 100; read, list, change, delete and restore; change or delete many at once; download the QR code as PNG or SVG, and read or set its style.
- Analytics: your organisation's figures and chart; a link's stats and its individual clicks.
- Events: report sign-ups, sales and other events against a click, a link or the organisation; list them; report an app open.
- Domains, folders, tags: list them and read one, to know what to put on a link.
- Integrations: create, list, test and delete webhooks, rotate their secret, and read their deliveries.
- Your key:
GET /meanswers who the key acts as. It works with a personal key only; an organisation key has no person, so it answers 403.
Every call, with its fields and answers, is in the API reference. API keys themselves are made, rolled and revoked only in the console, never through the API.
Permissions, rate limits and errors
- Permissions: a call needs the permission it names in the reference. Without it, the answer is 403 with
details.accesssaying which one, such asLinkManagement:CREATE. - Rate limits: calls are counted per organisation, with every key sharing the same count, per minute and per day. The limits depend on your plan; see pricing. Every answer carries
RateLimit-Remaining, so your code can slow down before it's refused. - Errors and retries: every status and code, the 429 answer, and how to retry a write without making it twice are in API errors.
Common questions
Can I call the Brevily API from a browser?
No. Anyone can read an API key shipped in a web page or an app, so call the Brevily API from your server and keep the secret in its environment or a secrets manager. See signing a request.
Is there a Brevily SDK?
Not yet. The Brevily API is plain HTTPS and JSON, so any HTTP client works, and this guide's samples cover the shell, Node and Python.
Can I create many short links in one Brevily API call?
Yes, if your plan includes it (see pricing): send a list of up to 100 link objects to POST /links. Each link is made or refused on its own, the answer gives a result for each in the order sent, and each counts as one call against your rate limit.
Do links made with the Brevily API show up in the console?
Yes. A link made through the API appears in Links straight away, and a link made in the console can be read over the API, within the key's permissions.
Next steps
- Sign an API request, so the secret never leaves your server.
- API errors, rate limits and safe retries, before you go to production.
- Click webhooks: hear about clicks as they happen instead of polling.
- MCP server: the same links from AI tools.
On this page