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
  1. How the Brevily URL shortener API works
  2. Create an API key with the right permissions
  3. Make your first API call
  4. Read a link and its clicks
  5. List links and page through them
  6. What the Brevily API covers
  7. Permissions, rate limits and errors
  8. Common questions
  9. Next steps

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

  1. Open Access › API keys and choose New key.
  2. 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.
  3. 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:

bash
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):

json
{  "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

js
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

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.

bash
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 counted clicks, and stats for the last 30 days.
  • GET /links/{link}/stats answers clicks, visitors and qrScans for the range, the change on the range before, and a day-by-day series.

Clicks are counted the same way as in the console, with bots kept apart; see what Brevily counts as a click.

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.

js
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 /me answers 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.access saying which one, such as LinkManagement: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

All developer guides

Brevily is invite-only, for now

Say what you would use it for and a person replies. Already invited? Sign in.