Sign in

How to read it

38 operations · one API version today: this is it

OpenAPI JSON

Each path below is called under https://console.brevily.com/api, with a key's x-api-key and x-api-secret headers or a signature (x-key-id, x-timestamp, x-nonce, x-signature). {OrganisationCode} stands for your organisation's code. A key holds only the permissions it was given, and every call answers inside its own organisation.

Auth

GET /me

Get the person behind the key

The person behind a personal key. An organisation’s key has no person (403). Changing the profile and ending sessions stay the console’s.

Responses

200 OK
idrequired string The person’s id.
emailrequired string The address they sign in with.
namerequired string Their name; null when none is set.
languagerequired string Their language (en, en-GB).
organisationCoderequired string Their organisation.
rolerequired "OWNER" | "ADMIN" | "MEMBER" Derived, never stored: the owner, else Admin or Billing by the system groups held, else MEMBER.
groupsrequired array of string The groups they sit in.
hasPasswordrequired boolean They can sign in with a password; false when they sign in through a provider only.
twoFactorrequired boolean Two-factor is on.
recoveryCodesLeftrequired number (integer) Unused recovery codes.
passkeysrequired number (integer) Passkeys registered.
signInsrequired array of string The providers linked to sign them in.
themerequired "system" | "light" | "dark" The console’s theme.
analyticsrequired boolean Usage analytics in the console: true on, false off; null when never asked.
emailsrequired object Each optional email (by its switch’s name) and whether they get it.
sessionsrequired array of
idrequired string The session’s id: what `POST /profile/sessions/{session}/revoke` takes.
devicerequired string The browser and system it was opened on.
methodrequired string How it signed in ("Password + 2FA", "GitHub"); null when not recorded.
placerequired string Where it signed in from, as the address placed it; null when unknown.
rememberrequired boolean "Keep me signed in" was ticked.
createdOnrequired string (date-time) When it signed in.
lastSeenOnrequired string (date-time) When it was last used; null when not recorded.
expiresOnrequired string (date-time) When it ends, the organisation’s session policy applied.
Their signed-in sessions, newest first.
createdOnrequired string (date-time) When the account was made.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

Organisation

GET /{OrganisationCode}/analytics/stats

Get the traffic figures

Parameters

name in type
OrganisationCoderequired path string
range query string Narrows the answer: `?range=<value>`, or `?range=eq:<value>`.
link query string Narrows the answer: `?link=<value>`, or `?link=eq:<value>`.
domain query string Narrows the answer: `?domain=<value>`, or `?domain=eq:<value>`.
compare query string Narrows the answer: `?compare=<value>`, or `?compare=eq:<value>`.
tag query string Narrows the answer: `?tag=<value>`, or `?tag=eq:<value>`.
folder query string Narrows the answer: `?folder=<value>`, or `?folder=eq:<value>`.
app query string Narrows the answer: `?app=<value>`, or `?app=eq:<value>`.
by query string Narrows the answer: `?by=<value>`, or `?by=eq:<value>`.
month query string Narrows the answer: `?month=<value>`, or `?month=eq:<value>`.
day query string Narrows the answer: `?day=<value>`, or `?day=eq:<value>`.
campaign query string Narrows the answer: `?campaign=<value>`, or `?campaign=eq:<value>`.
source query string Narrows the answer: `?source=<value>`, or `?source=eq:<value>`.
medium query string Narrows the answer: `?medium=<value>`, or `?medium=eq:<value>`.
q query string A search term.

Responses

200 OK
daysrequired number (integer) The days reported, in the organisation’s time zone: the range asked for, cut to what the plan keeps (0: it keeps none).
historyrequired number (integer) The days of daily totals the plan keeps; null for unlimited.
fromrequired string The first day, YYYY-MM-DD (the organisation’s time zone).
torequired string The last day, YYYY-MM-DD (the organisation’s time zone), today.
zonerequired string The IANA time zone the days are counted in: the organisation’s, or UTC when it set none.
clicksrequired
valuerequired number (integer) Over the whole range, today included.
changerequired
currentrequired number (integer) The range’s finished days.
previousrequired number (integer) As many days before them.
What a change is measured on; null when the plan keeps no days before the range, or the range has no finished day.
Human clicks.
uniqueVisitorsrequired
valuerequired number (integer) Over the whole range, today included.
changerequired
currentrequired number (integer) The range’s finished days.
previousrequired number (integer) As many days before them.
What a change is measured on; null when the plan keeps no days before the range, or the range has no finished day.
Unique visitors, summed per link per day.
qrScansrequired
valuerequired number (integer) Over the whole range, today included.
changerequired
currentrequired number (integer) The range’s finished days.
previousrequired number (integer) As many days before them.
What a change is measured on; null when the plan keeps no days before the range, or the range has no finished day.
Of the clicks, QR scans.
linksClickedrequired
valuerequired number (integer) Over the whole range, today included.
changerequired
currentrequired number (integer) The range’s finished days.
previousrequired number (integer) As many days before them.
What a change is measured on; null when the plan keeps no days before the range, or the range has no finished day.
Links clicked at least once.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

GET /{OrganisationCode}/analytics/chart

Get clicks per day

Parameters

name in type
OrganisationCoderequired path string
range query string Narrows the answer: `?range=<value>`, or `?range=eq:<value>`.
link query string Narrows the answer: `?link=<value>`, or `?link=eq:<value>`.
domain query string Narrows the answer: `?domain=<value>`, or `?domain=eq:<value>`.
compare query string Narrows the answer: `?compare=<value>`, or `?compare=eq:<value>`.
tag query string Narrows the answer: `?tag=<value>`, or `?tag=eq:<value>`.
folder query string Narrows the answer: `?folder=<value>`, or `?folder=eq:<value>`.
app query string Narrows the answer: `?app=<value>`, or `?app=eq:<value>`.
by query string Narrows the answer: `?by=<value>`, or `?by=eq:<value>`.
month query string Narrows the answer: `?month=<value>`, or `?month=eq:<value>`.
day query string Narrows the answer: `?day=<value>`, or `?day=eq:<value>`.
campaign query string Narrows the answer: `?campaign=<value>`, or `?campaign=eq:<value>`.
source query string Narrows the answer: `?source=<value>`, or `?source=eq:<value>`.
medium query string Narrows the answer: `?medium=<value>`, or `?medium=eq:<value>`.
q query string A search term.

Responses

200 OK
daysrequired number (integer) The days reported, in the organisation’s time zone: the range asked for, cut to what the plan keeps (0: it keeps none).
historyrequired number (integer) The days of daily totals the plan keeps; null for unlimited.
fromrequired string The first day, YYYY-MM-DD (the organisation’s time zone).
torequired string The last day, YYYY-MM-DD (the organisation’s time zone), today.
zonerequired string The IANA time zone the days are counted in: the organisation’s, or UTC when it set none.
seriesrequired array of
dayrequired string The day, YYYY-MM-DD, in the organisation’s time zone.
clicksrequired number (integer) Human clicks that day.
qrScansrequired number (integer) Of them, QR scans.
uniqueVisitorsrequired number (integer) Unique visitors that day.
One entry per day, oldest first.
previousrequired array of
dayrequired string The day, the range’s length before the series’ day.
clicksrequired number (integer) Human clicks that day; null for a day the plan no longer keeps.
The period before, a day per day of `series` (compare=1); null when not asked for.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

POST /{OrganisationCode}/links/{link}/clicks/{click}/events/{name}

Report an event against a click

Records what a tracked visit led to, against the click in the brv_click value the destination received (`<click id>.<link id>`): `sale` (with `amount` and `currency`, a secret key only), `install` (from an app, its install referrer or clipboard), `lead`, or any name of your own. Ids in the address win over the body. Answers 201 with the event, or 200 with `repeated: true` for one it already has.

Parameters

name in type
OrganisationCoderequired path string
linkrequired path string
clickrequired path string
namerequired path string

Request body

customer string Your id for the person (1-128 characters, no spaces): binds them to the click, or finds their first click.
amount number (integer) The amount in minor units (cents); needs currency. A sale needs both; a publishable key sends none.
currency string The amount’s ISO 4217 currency; needs amount.
id string Your own id for this event; a repeat of it is recorded once.
dedupe string The same as `id` (brv.js’s word); `id` wins when both are sent.
occurredAt string (date-time) When it happened, ISO 8601; now when left out. Not in the future.
properties
{
  "description": "Up to 15 names of your own, each starting with a letter, then letters, digits or _, at most 40 characters, with a text (at most 100 characters), number or true/false value, 2,048 bytes in all. Never personal data."
}
Up to 15 names of your own, each starting with a letter, then letters, digits or _, at most 40 characters, with a text (at most 100 characters), number or true/false value, 2,048 bytes in all. Never personal data.
key string A publishable key, when it cannot travel in the x-brevily-key header (sendBeacon).

Responses

201 Created
idrequired string The event’s id.
link string The link it is against; null for one against no link.
click string The click it is bound to (the id in brv_click); null for none.
event string What happened: sale, install, lead, or any name you report.
source "SERVER" | "DEVICE" | "WEB" Who reported it: a server with a secret key, an app with its key, or a site with its website key.
amount number (integer) The amount in minor units (cents); null for none.
currency string The amount’s ISO 4217 currency; null for none.
customer string Your id for the person; null when not given.
properties
{
  "description": "Its properties, as reported: names with a text, number or true/false value; {} for none."
}
Its properties, as reported: names with a text, number or true/false value; {} for none.
occurredAt string (date-time) When it happened.
repeatedrequired boolean It was recorded already (the same id, or the same click and event): answered 200, counted once.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

POST /{OrganisationCode}/links/{link}/events/{name}

Report an event against a link

Records an event against a link with no click (one is not known): its name as for a click’s, the URL’s link winning over the body. Answers 201 with the event, or 200 with `repeated: true`.

Parameters

name in type
OrganisationCoderequired path string
linkrequired path string
namerequired path string

Request body

customer string Your id for the person (1-128 characters, no spaces): binds them to the click, or finds their first click.
amount number (integer) The amount in minor units (cents); needs currency. A sale needs both; a publishable key sends none.
currency string The amount’s ISO 4217 currency; needs amount.
id string Your own id for this event; a repeat of it is recorded once.
dedupe string The same as `id` (brv.js’s word); `id` wins when both are sent.
occurredAt string (date-time) When it happened, ISO 8601; now when left out. Not in the future.
properties
{
  "description": "Up to 15 names of your own, each starting with a letter, then letters, digits or _, at most 40 characters, with a text (at most 100 characters), number or true/false value, 2,048 bytes in all. Never personal data."
}
Up to 15 names of your own, each starting with a letter, then letters, digits or _, at most 40 characters, with a text (at most 100 characters), number or true/false value, 2,048 bytes in all. Never personal data.
key string A publishable key, when it cannot travel in the x-brevily-key header (sendBeacon).

Responses

201 Created
idrequired string The event’s id.
link string The link it is against; null for one against no link.
click string The click it is bound to (the id in brv_click); null for none.
event string What happened: sale, install, lead, or any name you report.
source "SERVER" | "DEVICE" | "WEB" Who reported it: a server with a secret key, an app with its key, or a site with its website key.
amount number (integer) The amount in minor units (cents); null for none.
currency string The amount’s ISO 4217 currency; null for none.
customer string Your id for the person; null when not given.
properties
{
  "description": "Its properties, as reported: names with a text, number or true/false value; {} for none."
}
Its properties, as reported: names with a text, number or true/false value; {} for none.
occurredAt string (date-time) When it happened.
repeatedrequired boolean It was recorded already (the same id, or the same click and event): answered 200, counted once.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

POST /{OrganisationCode}/events/open

Open a link in its app

What an app sends when one of its links opened it (Universal Links, App Links): `url`, the link as the app was handed it. The edge decides the visit as any other and counts its click; the answer is `{ open: "app", path, brvClick }` to stay in the app at `path`, or `{ open: "browser", url }` to hand the visit to the browser (an expired, disabled, password-protected or otherwise unopenable link). From an app’s publishable key, or a secret key; an app’s key answers 404 for a link whose deep link opens another app, or on a domain not picked for its app.

Parameters

name in type
OrganisationCoderequired path string
user-agent header string

Request body

urlrequired string The link the app was opened with, as it was handed it.
key string The app’s publishable key, when it cannot travel in the x-brevily-key header.

Responses

200 OK
openrequired "app" | "browser" app: show `path` in the app. browser: open `url` in the browser.
path string The path inside the app (the link’s deep link, with the visit’s query); with app only.
brvClick string The visit’s click as <click id>.<link id>: what the app reports `install` and its events with; null when no click was counted. With app only.
url string Where the browser goes; with browser only.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

POST /{OrganisationCode}/events/{name}

Report an event

Records an event against the organisation: with a `customer` already reported against a click, against that customer’s first click (first touch); else against no link. Any link or click in the body is ignored: name them in the address. Answers 201 with the event, or 200 with `repeated: true`.

Parameters

name in type
OrganisationCoderequired path string
namerequired path string

Request body

customer string Your id for the person (1-128 characters, no spaces): binds them to the click, or finds their first click.
amount number (integer) The amount in minor units (cents); needs currency. A sale needs both; a publishable key sends none.
currency string The amount’s ISO 4217 currency; needs amount.
id string Your own id for this event; a repeat of it is recorded once.
dedupe string The same as `id` (brv.js’s word); `id` wins when both are sent.
occurredAt string (date-time) When it happened, ISO 8601; now when left out. Not in the future.
properties
{
  "description": "Up to 15 names of your own, each starting with a letter, then letters, digits or _, at most 40 characters, with a text (at most 100 characters), number or true/false value, 2,048 bytes in all. Never personal data."
}
Up to 15 names of your own, each starting with a letter, then letters, digits or _, at most 40 characters, with a text (at most 100 characters), number or true/false value, 2,048 bytes in all. Never personal data.
key string A publishable key, when it cannot travel in the x-brevily-key header (sendBeacon).

Responses

201 Created
idrequired string The event’s id.
link string The link it is against; null for one against no link.
click string The click it is bound to (the id in brv_click); null for none.
event string What happened: sale, install, lead, or any name you report.
source "SERVER" | "DEVICE" | "WEB" Who reported it: a server with a secret key, an app with its key, or a site with its website key.
amount number (integer) The amount in minor units (cents); null for none.
currency string The amount’s ISO 4217 currency; null for none.
customer string Your id for the person; null when not given.
properties
{
  "description": "Its properties, as reported: names with a text, number or true/false value; {} for none."
}
Its properties, as reported: names with a text, number or true/false value; {} for none.
occurredAt string (date-time) When it happened.
repeatedrequired boolean It was recorded already (the same id, or the same click and event): answered 200, counted once.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

GET /{OrganisationCode}/events

List events

The latest events, newest first, 25 a page: ?range=7d|30d|90d (what the plan keeps; 30d by default), ?link=<id>, ?event=<name>, ?source=SERVER|DEVICE|WEB, ?tag=<id>, ?folder=<code>, ?app=<id> (the links whose deep link opens that app). The next page's cursor is the x-next-cursor header: send it back as ?before=.

Parameters

name in type
OrganisationCoderequired path string
range query string Narrows the answer: `?range=<value>`, or `?range=eq:<value>`.
link query string Narrows the answer: `?link=<value>`, or `?link=eq:<value>`.
event query string Narrows the answer: `?event=<value>`, or `?event=eq:<value>`.
source query string Narrows the answer: `?source=<value>`, or `?source=eq:<value>`.
before query string Narrows the answer: `?before=<value>`, or `?before=eq:<value>`.
after query string Narrows the answer: `?after=<value>`, or `?after=eq:<value>`.
tag query string Narrows the answer: `?tag=<value>`, or `?tag=eq:<value>`.
by query string Narrows the answer: `?by=<value>`, or `?by=eq:<value>`.
size query string Narrows the answer: `?size=<value>`, or `?size=eq:<value>`.
folder query string Narrows the answer: `?folder=<value>`, or `?folder=eq:<value>`.
app query string Narrows the answer: `?app=<value>`, or `?app=eq:<value>`.
q query string A search term.

Responses

200 OK
array of
idrequired string The event’s id.
linkrequired string The link it is against; null for one against no link.
clickrequired string The click it is bound to (the id in brv_click); null for none.
eventrequired string What happened: sale, install, lead, or any name you report.
sourcerequired "SERVER" | "DEVICE" | "WEB" Who reported it: a server with a secret key, an app with its key, or a site with its website key.
amountrequired number (integer) The amount in minor units (cents); null for none.
currencyrequired string The amount’s ISO 4217 currency; null for none.
customerrequired string Your id for the person; null when not given.
propertiesrequired
{
  "description": "Its properties, as reported: names with a text, number or true/false value; {} for none."
}
Its properties, as reported: names with a text, number or true/false value; {} for none.
occurredAtrequired string (date-time) When it happened.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

POST /{OrganisationCode}/events

Report events in bulk

Up to 100 events: each row `{ name, link?, click?, … }` as one event's body, the link and click named in the row. Each row is recorded or refused by itself, and the answer lists each in order: `{ status, event?, error? }` (201 recorded, 200 a repeat, else the refusal's status and its envelope). Send an `id` with each so a retry records nothing twice.

Parameters

name in type
OrganisationCoderequired path string

Request body

array of
namerequired string The event’s name: sale, install, lead or your own.
link string The link it is against.
click string The click it is bound to (the id in brv_click), with its link.
customer string Your id for the person.
amount number (integer) The amount in minor units; needs currency.
currency string The amount’s ISO 4217 currency.
id string Your own id for it; a repeat is recorded once.
occurredAt string (date-time) When it happened, ISO 8601.
properties
{
  "description": "Its properties, as for one event."
}
Its properties, as for one event.

Responses

200 OK
array of
statusrequired number (integer) 201 recorded, 200 a repeat, else the refusal’s status.
event
{
  "description": "The event recorded, as a single report answers it."
}
The event recorded, as a single report answers it.
error
{
  "description": "The refusal: its code, message and details."
}
The refusal: its code, message and details.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

GET /{OrganisationCode}/domains

List domains

An organisation’s own domains, by name: ?q= searches the hostname, ?status= narrows to one status, ?sort=domain|status.

Parameters

name in type
OrganisationCoderequired path string
page query integer 1-based page number. Overrides the header.
limit query integer Page size. Overrides the header.
x-page-number header integer 1-based page number.
x-page-size header integer Page size.
status query string Narrows the answer: `?status=<value>`, or `?status=eq:<value>`.
add query string Narrows the answer: `?add=<value>`, or `?add=eq:<value>`.
checked query string Narrows the answer: `?checked=<value>`, or `?checked=eq:<value>`.
domain query string Narrows the answer: `?domain=<value>`, or `?domain=eq:<value>`.
q query string A search term.
sort query string One of domain, status, then :asc or :desc (`?sort=domain:desc`).

Responses

200 OK
array of
domainrequired string The hostname, lower case.
namerequired string The name it is listed under.
sharedrequired boolean One of Brevily’s shared domains; false for an organisation’s own.
statusrequired "PENDING" | "VERIFIED" | "SUSPENDED" | "DELETED" PENDING until its DNS record proves it (a requested subdomain: until it is approved); DELETED once removed while links named it.
parentrequired string The shared domain a requested subdomain sits under; null for any other domain.
offersSubdomainsrequired boolean A shared domain organisations may ask a subdomain of; false for any other domain.
planStatusrequired "ACTIVE" | "CHOOSE" | "KEEP" | "PARKED" Against the plan: serving, being chosen between, picked to stay, or switched off.
choiceDueOnrequired string (date-time) When an open choice of the domains to keep is due; null when none is.
isDefaultrequired boolean The shared domain a new link lands on when none is chosen.
purposerequired "LINKS" | "SHARES" | "PARTNER" | "CAMPAIGN" LINKS, or only one kind: the short links of shared reports and public link stats (SHARES), partners’ referral links (PARTNER) or Brevily’s own campaign links (CAMPAIGN).
methodrequired "DNS_TXT" The record that proves it (that proved it, once verified): its TXT record; null when none.
verifiedOnrequired string (date-time) When it was proved; null while it has not been.
heldUntilrequired string (date-time) An unverified claim holds its name until then; null otherwise.
freeOnrequired string (date-time) A removed own domain holds its name until then; null otherwise.
certificaterequired
statusrequired string PENDING, ISSUED or FAILED.
issuedOnrequired string (date-time) When it was issued; null until it is.
expiresOnrequired string (date-time) When it expires; null until it is issued.
recordsrequired array of
typerequired "TXT" | "A" | "AAAA" The record’s type.
namerequired string The name the record sits at.
valuerequired string What it holds.
ttlrequired string Its time to live ("Auto": the provider’s default).
The DNS records to add: the one that proves it, and the ones that connect it.
linksrequired number (integer) Links on it that still answer (active, disabled, expired).
slugLengthrequired number (integer) How long a generated back-half is now (it grows with use).
slugModerequired "RANDOM" | "SEQUENTIAL" | "SHUFFLED" How generated back-halves are drawn.
allowChosenSlugsrequired boolean People may type their own back-half on it.
allowSlugModeOverriderequired boolean A link may pick the other generator.
defaultRedirectUrlrequired string Where its root sends visitors; null for the default.
notFoundRedirectUrlrequired string Where an unknown back-half sends visitors; null for the default page.
expiredRedirectUrlrequired string Where an expired link sends visitors; null for the default page.
disabledRedirectUrlrequired string Where a disabled link sends visitors; null for the default page.
passClickIdsrequired boolean An own domain’s default: its links pass the ad networks’ click ids (gclid, fbclid, msclkid and the rest) from the visit, unless a link or its folder chooses for itself. True until set false.
passNamesrequired array of string An own domain’s default: other names of the visit’s parameters its links pass on beside utm_ ones (never a redirect’s, such as next or url).
createdOnrequired string (date-time) When it was added.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

GET /{OrganisationCode}/domains/{domain}

Get a domain

Parameters

name in type
OrganisationCoderequired path string
domainrequired path string
status query string Narrows the answer: `?status=<value>`, or `?status=eq:<value>`.
add query string Narrows the answer: `?add=<value>`, or `?add=eq:<value>`.
checked query string Narrows the answer: `?checked=<value>`, or `?checked=eq:<value>`.
q query string A search term.
sort query string One of domain, status, then :asc or :desc (`?sort=domain:desc`).

Responses

200 OK
domainrequired string The hostname, lower case.
namerequired string The name it is listed under.
sharedrequired boolean One of Brevily’s shared domains; false for an organisation’s own.
statusrequired "PENDING" | "VERIFIED" | "SUSPENDED" | "DELETED" PENDING until its DNS record proves it (a requested subdomain: until it is approved); DELETED once removed while links named it.
parentrequired string The shared domain a requested subdomain sits under; null for any other domain.
offersSubdomainsrequired boolean A shared domain organisations may ask a subdomain of; false for any other domain.
planStatusrequired "ACTIVE" | "CHOOSE" | "KEEP" | "PARKED" Against the plan: serving, being chosen between, picked to stay, or switched off.
choiceDueOnrequired string (date-time) When an open choice of the domains to keep is due; null when none is.
isDefaultrequired boolean The shared domain a new link lands on when none is chosen.
purposerequired "LINKS" | "SHARES" | "PARTNER" | "CAMPAIGN" LINKS, or only one kind: the short links of shared reports and public link stats (SHARES), partners’ referral links (PARTNER) or Brevily’s own campaign links (CAMPAIGN).
methodrequired "DNS_TXT" The record that proves it (that proved it, once verified): its TXT record; null when none.
verifiedOnrequired string (date-time) When it was proved; null while it has not been.
heldUntilrequired string (date-time) An unverified claim holds its name until then; null otherwise.
freeOnrequired string (date-time) A removed own domain holds its name until then; null otherwise.
certificaterequired
statusrequired string PENDING, ISSUED or FAILED.
issuedOnrequired string (date-time) When it was issued; null until it is.
expiresOnrequired string (date-time) When it expires; null until it is issued.
recordsrequired array of
typerequired "TXT" | "A" | "AAAA" The record’s type.
namerequired string The name the record sits at.
valuerequired string What it holds.
ttlrequired string Its time to live ("Auto": the provider’s default).
The DNS records to add: the one that proves it, and the ones that connect it.
linksrequired number (integer) Links on it that still answer (active, disabled, expired).
slugLengthrequired number (integer) How long a generated back-half is now (it grows with use).
slugModerequired "RANDOM" | "SEQUENTIAL" | "SHUFFLED" How generated back-halves are drawn.
allowChosenSlugsrequired boolean People may type their own back-half on it.
allowSlugModeOverriderequired boolean A link may pick the other generator.
defaultRedirectUrlrequired string Where its root sends visitors; null for the default.
notFoundRedirectUrlrequired string Where an unknown back-half sends visitors; null for the default page.
expiredRedirectUrlrequired string Where an expired link sends visitors; null for the default page.
disabledRedirectUrlrequired string Where a disabled link sends visitors; null for the default page.
passClickIdsrequired boolean An own domain’s default: its links pass the ad networks’ click ids (gclid, fbclid, msclkid and the rest) from the visit, unless a link or its folder chooses for itself. True until set false.
passNamesrequired array of string An own domain’s default: other names of the visit’s parameters its links pass on beside utm_ ones (never a redirect’s, such as next or url).
createdOnrequired string (date-time) When it was added.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

GET /{OrganisationCode}/integrations

List the integrations

The organisation’s integrations, oldest first, with this billing period’s deliveries. Their deliveries are GET /integrations/deliveries.

Parameters

name in type
OrganisationCoderequired path string
status query string Narrows the answer: `?status=<value>`, or `?status=eq:<value>`.
before query string Narrows the answer: `?before=<value>`, or `?before=eq:<value>`.
after query string Narrows the answer: `?after=<value>`, or `?after=eq:<value>`.
add query string Narrows the answer: `?add=<value>`, or `?add=eq:<value>`.
events query string Narrows the answer: `?events=<value>`, or `?events=eq:<value>`.
folder query string Narrows the answer: `?folder=<value>`, or `?folder=eq:<value>`.
q query string A search term.

Responses

200 OK
array of
idrequired string The integration’s id.
kindrequired "WEBHOOK" | "GA4" | "PIXEL" A signed webhook, GA4 forwarding (Measurement Protocol), or an ad pixel the links that name it fire in the visitor’s browser.
urlrequired string A webhook’s https address; null for every other kind.
measurementIdrequired string A GA4 stream’s measurement id; null for every other kind.
platformrequired "META" | "LINKEDIN" | "X" | "GOOGLE_ADS" | "MICROSOFT_ADS" | "PINTEREST" An ad pixel’s ad network; null for every other kind.
pixelIdrequired string An ad pixel’s id at its ad network (Google Ads: its conversion id, AW-…); null for every other kind.
linkIdrequired string The one link it sends; null for every link (and for a pixel, which the links that name it fire).
folderrequired string The code of the one folder it sends the links of (those in it now: a link moved out stops matching, one moved in starts); null for every link or one link.
eventsrequired array of "link.click" | "link.created" | "link.updated" | "link.expired" | "link.broken" | "event.reported" What it receives: a webhook’s choice (link.click when none was chosen), GA4’s link.click alone, a pixel’s nothing.
statusrequired "ACTIVE" | "DISABLED" DISABLED queues nothing; turning one off gives up what it still owed.
activeSincerequired string (date-time) Clicks from then on are sent (when it was made or last turned on).
sentrequired number (integer) Deliveries sent this billing period.
failedrequired number (integer) Deliveries given up this billing period.
lastSentOnrequired string (date-time) Its last delivery sent this billing period; null for none.
createdOnrequired string (date-time) When it was made.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

POST /{OrganisationCode}/integrations

Add an integration

Adds a webhook (`kind` WEBHOOK, `url`, and optionally `events`: which of link.click, link.created, link.updated, link.expired, link.broken and event.reported it receives — clicks when left out) or GA4 forwarding (`kind` GA4, `measurementId`, `apiSecret`), for every link, one link (`link`, as domain/back-half) or one folder (`folder`, its code: the links in it as they come and go, on a plan with folder webhooks; one for every link is for people who see every folder), or an ad pixel (`kind` PIXEL, `platform`, `pixelId`), which the links that name it fire. Every kind counts against the plan’s integrations. Answers 201 with the webhook’s signing secret, shown this once.

Parameters

name in type
OrganisationCoderequired path string

Request body

kind "WEBHOOK" | "GA4" | "PIXEL" WEBHOOK when left out.
url string A webhook’s https address.
events array of "link.click" | "link.created" | "link.updated" | "link.expired" | "link.broken" | "event.reported" The events a webhook receives; link.click when left out.
measurementId string GA4: the stream’s measurement id.
apiSecret string GA4: the stream’s Measurement Protocol secret.
platform "META" | "LINKEDIN" | "X" | "GOOGLE_ADS" | "MICROSOFT_ADS" | "PINTEREST" A pixel’s ad network.
pixelId string A pixel’s id at its ad network.
link string Send one link only, as domain/back-half; not with folder, and not for a pixel.
folder string Send one folder’s links only, by its code; not with link, and not for a pixel.

Responses

201 Created
idrequired string The integration’s id.
kindrequired "WEBHOOK" | "GA4" | "PIXEL" A signed webhook, GA4 forwarding (Measurement Protocol), or an ad pixel the links that name it fire in the visitor’s browser.
urlrequired string A webhook’s https address; null for every other kind.
measurementIdrequired string A GA4 stream’s measurement id; null for every other kind.
platformrequired "META" | "LINKEDIN" | "X" | "GOOGLE_ADS" | "MICROSOFT_ADS" | "PINTEREST" An ad pixel’s ad network; null for every other kind.
pixelIdrequired string An ad pixel’s id at its ad network (Google Ads: its conversion id, AW-…); null for every other kind.
linkIdrequired string The one link it sends; null for every link (and for a pixel, which the links that name it fire).
folderrequired string The code of the one folder it sends the links of (those in it now: a link moved out stops matching, one moved in starts); null for every link or one link.
eventsrequired array of "link.click" | "link.created" | "link.updated" | "link.expired" | "link.broken" | "event.reported" What it receives: a webhook’s choice (link.click when none was chosen), GA4’s link.click alone, a pixel’s nothing.
statusrequired "ACTIVE" | "DISABLED" DISABLED queues nothing; turning one off gives up what it still owed.
activeSincerequired string (date-time) Clicks from then on are sent (when it was made or last turned on).
sentrequired number (integer) Deliveries sent this billing period.
failedrequired number (integer) Deliveries given up this billing period.
lastSentOnrequired string (date-time) Its last delivery sent this billing period; null for none.
createdOnrequired string (date-time) When it was made.
secretrequired string A webhook’s signing secret (whsec_…), shown on this answer only: keep it to verify X-Brevily-Signature. Null for every other kind.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

GET /{OrganisationCode}/integrations/deliveries

List integration deliveries

Newest first, 20 a page; ?status=sent|retrying|gaveup narrows them (gave up: this billing period's), ?folder=<code> to the integrations made for that folder. The next page's cursor is the x-next-cursor header: send it back as ?before=.

Parameters

name in type
OrganisationCoderequired path string
status query string Narrows the answer: `?status=<value>`, or `?status=eq:<value>`.
before query string Narrows the answer: `?before=<value>`, or `?before=eq:<value>`.
after query string Narrows the answer: `?after=<value>`, or `?after=eq:<value>`.
add query string Narrows the answer: `?add=<value>`, or `?add=eq:<value>`.
events query string Narrows the answer: `?events=<value>`, or `?events=eq:<value>`.
folder query string Narrows the answer: `?folder=<value>`, or `?folder=eq:<value>`.
q query string A search term.

Responses

200 OK
array of
idrequired string The delivery’s id (its X-Brevily-Delivery when sent).
torequired string Where it goes: a webhook’s host, or “GA4 · <id>”.
eventrequired "link.click" | "link.created" | "link.updated" | "link.expired" | "link.broken" | "event.reported" What it delivers: link.click, or another event the webhook chose.
linkIdrequired string The link it names; null when unknown.
linkrequired string The short link it names (domain/back-half); null when unknown.
statusrequired "QUEUED" | "RETRYING" | "SENT" | "DEAD" | "SKIPPED" QUEUED (not tried yet), RETRYING (a try failed; it is tried again), SENT, DEAD (given up), or SKIPPED (past the plan’s deliveries: never sent, never charged).
attemptrequired number (integer) Attempts so far.
responseStatusrequired number (integer) The receiver’s last HTTP status; null for none.
lastErrorrequired string Why the last attempt failed; null when none did.
lastResponserequired string The first 500 characters of the receiver’s answer to the last attempt; null for none.
durationMsrequired number (integer) How long the last attempt took, in milliseconds.
nextAttemptOnrequired string (date-time) A queued delivery’s next attempt; else null.
createdOnrequired string (date-time) When it was queued.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

DELETE /{OrganisationCode}/integrations/{integration}

Delete an integration

Answers 204: the integration is gone and sends nothing more.

Parameters

name in type
OrganisationCoderequired path string
integrationrequired path string

Responses

204 No content
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

POST /{OrganisationCode}/integrations/{integration}/tests

Send a test event to an integration

Sends a signed sample of `event` (one the webhook receives; link.click when left out) now.

Parameters

name in type
OrganisationCoderequired path string
integrationrequired path string

Request body

event "link.click" | "link.created" | "link.updated" | "link.expired" | "link.broken" | "event.reported" An event the webhook receives; link.click when left out.

Responses

200 OK
idrequired string The integration’s id.
targetrequired string Where it was sent: the webhook’s URL, or the GA4 id.
okrequired boolean The receiver answered 2xx (and GA4 found nothing to reject).
statusrequired number (integer) The receiver’s HTTP status; null when nothing answered.
errorrequired string Why nothing answered; else null.
messagesrequired array of string What GA4 would reject (GA4 only).
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

PUT /{OrganisationCode}/integrations/{integration}/secret

Roll a webhook’s signing secret

Parameters

name in type
OrganisationCoderequired path string
integrationrequired path string

Responses

200 OK
idrequired string The integration’s id.
kindrequired "WEBHOOK" | "GA4" | "PIXEL" A signed webhook, GA4 forwarding (Measurement Protocol), or an ad pixel the links that name it fire in the visitor’s browser.
urlrequired string A webhook’s https address; null for every other kind.
measurementIdrequired string A GA4 stream’s measurement id; null for every other kind.
platformrequired "META" | "LINKEDIN" | "X" | "GOOGLE_ADS" | "MICROSOFT_ADS" | "PINTEREST" An ad pixel’s ad network; null for every other kind.
pixelIdrequired string An ad pixel’s id at its ad network (Google Ads: its conversion id, AW-…); null for every other kind.
linkIdrequired string The one link it sends; null for every link (and for a pixel, which the links that name it fire).
folderrequired string The code of the one folder it sends the links of (those in it now: a link moved out stops matching, one moved in starts); null for every link or one link.
eventsrequired array of "link.click" | "link.created" | "link.updated" | "link.expired" | "link.broken" | "event.reported" What it receives: a webhook’s choice (link.click when none was chosen), GA4’s link.click alone, a pixel’s nothing.
statusrequired "ACTIVE" | "DISABLED" DISABLED queues nothing; turning one off gives up what it still owed.
activeSincerequired string (date-time) Clicks from then on are sent (when it was made or last turned on).
sentrequired number (integer) Deliveries sent this billing period.
failedrequired number (integer) Deliveries given up this billing period.
lastSentOnrequired string (date-time) Its last delivery sent this billing period; null for none.
createdOnrequired string (date-time) When it was made.
secretrequired string A webhook’s signing secret (whsec_…), shown on this answer only: keep it to verify X-Brevily-Signature. Null for every other kind.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
409 A request with this Idempotency-Key is still running.
RapidError
413 The body is larger than the API takes.
RapidError
415 The body is not JSON.
RapidError
422 This Idempotency-Key was used on another request.
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

Folders

GET /{OrganisationCode}/folders

List the organisation’s folders

The organisation’s folders: the default one first, then by name.

Parameters

name in type
OrganisationCoderequired path string

Responses

200 OK
array of
idrequired string The folder’s id.
coderequired string The folder’s address in the API (`/folders/<code>/links`): lower-case letters, digits and single dashes.
namerequired string The folder’s name.
isDefaultrequired boolean The organisation’s default folder: where a link goes when none is named. It can be renamed, never deleted.
linksrequired number (integer) Links in it (deleted ones not counted).
utmrequired
source string utm_source, copied into a new link.
medium string utm_medium, copied into a new link.
campaign string utm_campaign, copied into a new link.
term string utm_term, copied into a new link.
content string utm_content, copied into a new link.
The UTM tags a new link starts with; null for none.
paramsrequired
clickIdsrequired boolean Ad click ids (gclid, fbclid, msclkid and the rest) pass from the visit.
namesrequired array of string Other names of the visit’s parameters that pass (never a redirect’s, such as next or url).
Which of the visit’s own parameters a new link passes on beyond utm_ ones: null follows each link’s own domain; clickIds false with no names passes none, whatever the domain passes.
domainrequired string The short domain a new link starts on; null for none.
apprequired
appIdrequired string The organisation’s mobile app.
pathrequired string The screen in the app.
fallbackrequired "WEB" | "STORE" Where a visitor without the app goes.
The mobile app a new link opens; null for none.
qrrequired
{
  "description": "The QR code style a new link starts with (fg, bg, moduleShape, logo: SMALL, MEDIUM or LARGE, quietZone); null for none."
}
The QR code style a new link starts with (fg, bg, moduleShape, logo: SMALL, MEDIUM or LARGE, quietZone); null for none.
tagsrequired array of
namerequired string The tag as typed.
kindrequired "PERSON" | "TEAM" | "CAMPAIGN" | "CHANNEL" | "PRODUCT" | "REGION" | "CUSTOM" What the tag names.
The tags a new link starts with.
pixelsrequired array of string The ad pixels a new link fires, by integration id.
locksrequired array of "utm" | "params" | "domain" | "app" | "qr" | "tags" | "pixels" The locked preset fields.
restrictedrequired boolean Whether the folder is restricted to the people listed at `/folders/<code>/access`: only they, Admin and the organisation’s owner see its links and figures. False: open to everyone in the organisation.
createdOnrequired string (date-time) When it was made.
updatedOnrequired string (date-time) When it last changed; null when it never has.
impact
followingrequired number (integer) Links that follow a field the change touches.
ownrequired number (integer) Links with their own value for a touched field the folder does not lock: kept unless `force` is true.
forcedrequired number (integer) Links with their own value for a field the change locks: the lock forces the folder’s value onto them.
editsrequired number (integer) Links that will change, one link edit each (links keeping their own value cost nothing).
What the change does to the folder’s existing links.
presetJob
idrequired string The job’s id.
statusrequired "PENDING" | "DONE" | "FAILED" PENDING while links are still being updated.
fieldsrequired array of "utm" | "params" | "domain" | "app" | "qr" | "tags" | "pixels" The preset fields the job applies.
forcerequired boolean Whether links with their own value were included.
reservedrequired number (integer) Destination edits set aside for it.
changedrequired number (integer) Links updated so far.
skippedrequired number (integer) Links left alone because the edits reserved ran out.
refundedrequired number (integer) Reserved edits given back (when the job ended).
errorrequired string Why a failed job stopped.
createdOnrequired string (date-time) When the change was made.
finishedOnrequired string (date-time) When the job ended; null while it runs.
A folder’s preset change as the background job applies it.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

GET /{OrganisationCode}/folders/{folder}

Get a folder

Parameters

name in type
OrganisationCoderequired path string
folderrequired path string

Responses

200 OK
idrequired string The folder’s id.
coderequired string The folder’s address in the API (`/folders/<code>/links`): lower-case letters, digits and single dashes.
namerequired string The folder’s name.
isDefaultrequired boolean The organisation’s default folder: where a link goes when none is named. It can be renamed, never deleted.
linksrequired number (integer) Links in it (deleted ones not counted).
utmrequired
source string utm_source, copied into a new link.
medium string utm_medium, copied into a new link.
campaign string utm_campaign, copied into a new link.
term string utm_term, copied into a new link.
content string utm_content, copied into a new link.
The UTM tags a new link starts with; null for none.
paramsrequired
clickIdsrequired boolean Ad click ids (gclid, fbclid, msclkid and the rest) pass from the visit.
namesrequired array of string Other names of the visit’s parameters that pass (never a redirect’s, such as next or url).
Which of the visit’s own parameters a new link passes on beyond utm_ ones: null follows each link’s own domain; clickIds false with no names passes none, whatever the domain passes.
domainrequired string The short domain a new link starts on; null for none.
apprequired
appIdrequired string The organisation’s mobile app.
pathrequired string The screen in the app.
fallbackrequired "WEB" | "STORE" Where a visitor without the app goes.
The mobile app a new link opens; null for none.
qrrequired
{
  "description": "The QR code style a new link starts with (fg, bg, moduleShape, logo: SMALL, MEDIUM or LARGE, quietZone); null for none."
}
The QR code style a new link starts with (fg, bg, moduleShape, logo: SMALL, MEDIUM or LARGE, quietZone); null for none.
tagsrequired array of
namerequired string The tag as typed.
kindrequired "PERSON" | "TEAM" | "CAMPAIGN" | "CHANNEL" | "PRODUCT" | "REGION" | "CUSTOM" What the tag names.
The tags a new link starts with.
pixelsrequired array of string The ad pixels a new link fires, by integration id.
locksrequired array of "utm" | "params" | "domain" | "app" | "qr" | "tags" | "pixels" The locked preset fields.
restrictedrequired boolean Whether the folder is restricted to the people listed at `/folders/<code>/access`: only they, Admin and the organisation’s owner see its links and figures. False: open to everyone in the organisation.
createdOnrequired string (date-time) When it was made.
updatedOnrequired string (date-time) When it last changed; null when it never has.
impact
followingrequired number (integer) Links that follow a field the change touches.
ownrequired number (integer) Links with their own value for a touched field the folder does not lock: kept unless `force` is true.
forcedrequired number (integer) Links with their own value for a field the change locks: the lock forces the folder’s value onto them.
editsrequired number (integer) Links that will change, one link edit each (links keeping their own value cost nothing).
What the change does to the folder’s existing links.
presetJob
idrequired string The job’s id.
statusrequired "PENDING" | "DONE" | "FAILED" PENDING while links are still being updated.
fieldsrequired array of "utm" | "params" | "domain" | "app" | "qr" | "tags" | "pixels" The preset fields the job applies.
forcerequired boolean Whether links with their own value were included.
reservedrequired number (integer) Destination edits set aside for it.
changedrequired number (integer) Links updated so far.
skippedrequired number (integer) Links left alone because the edits reserved ran out.
refundedrequired number (integer) Reserved edits given back (when the job ended).
errorrequired string Why a failed job stopped.
createdOnrequired string (date-time) When the change was made.
finishedOnrequired string (date-time) When the job ended; null while it runs.
A folder’s preset change as the background job applies it.
400 Bad request
RapidError
401 Unauthenticated
RapidError
403 Forbidden
RapidError
404 Not found
RapidError
429 Too many requests: wait as Retry-After says.
RapidError
500 Internal server error
RapidError

Schemas

RapidError

coderequired "UNHANDLED" | "CONFIG" | "VALIDATION_FAILED" | "QUERY_INVALID" | "RESPONSE_INVALID" | "TEMPLATE_RENDER" | "UNAUTHENTICATED" | "ACCESS_DENIED" | "AUTH_UNBOUND" | "AUTH_UNAVAILABLE" | "CACHE_UNBOUND" | "COMPOSE_UNKNOWN_ACTION" | "COMPOSE_PARTS" | "CSRF_INVALID" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "CONFLICT" | "IDEMPOTENCY_KEY_INVALID" | "IDEMPOTENCY_IN_FLIGHT" | "IDEMPOTENCY_MISMATCH" | "PAYLOAD_TOO_LARGE" | "UNSUPPORTED_MEDIA" | "TIMEOUT" | "RATE_LIMITED" | "UPLOADS_UNAVAILABLE"
messagerequired string
details object Client-safe detail — on every 4xx; dropped from 5xx in PRODUCTION.
debug object DEVELOPMENT only — never sent in PRODUCTION.
requestIdrequired string