Links › List the organisation’s links
Links
List the organisation’s links
GET/api/{ORG}/linksPermalink
Answers a list of Link, one page at a time.
- Permission
- Links · view
- Plan
- Plans that include the API: Pricing
- Retry
- Safe: a read changes nothing
Example request
curl "https://console.brevily.com/api/NORTHWIND/links" \ -H "x-api-key: brv_ak_7Fq2Lw9xK3" \ -H "x-api-secret: $BREVILY_SECRET"const res = await fetch("https://console.brevily.com/api/NORTHWIND/links", { headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, },});const answer = await res.json();Example answer
[ { "id": "01JC6Y8QH2M4ZK7T9VRW3XNB5D", "domain": "go.example.com", "slug": "example", "path": "example", "shortUrl": "https://www.example.com/sale/autumn", "folder": "example", "move": { "edits": 1, "fields": [ "utm" ] }, "inherited": [ "utm" ], "title": "example", "note": "example", "destination": "https://www.example.com/sale/autumn", "opens": "https://www.example.com/sale/autumn", "status": "ACTIVE", "state": "ACTIVE", "slugChosen": false, "tags": [ { "name": "example", "kind": "PERSON" } ], "utm": { "source": "example", "medium": "example", "campaign": "example", "term": "example", "content": "example" }, "passMode": "FOLLOW", "passClickIds": false, "passNames": [ "example" ], "ogTitle": "example", "ogDescription": "example", "ogImage": "example", "liveOn": "2026-11-05T09:41:00Z", "expiresOn": "2026-11-05T09:41:00Z", "endedOn": "2026-11-05T09:41:00Z", "trashedOn": "2026-11-05T09:41:00Z", "maxClicks": 1, "clicks": 1, "hasPassword": false, "masked": false, "trackConversions": false, "publicStats": false, "qrStyled": false, "health": "UNKNOWN", "healthReason": "example", "flagged": false, "threat": "example", "reviewRequestedOn": "2026-11-05T09:41:00Z", "createdBy": "example", "createdOn": "2026-11-05T09:41:00Z", "updatedOn": "2026-11-05T09:41:00Z" }]{ "code": "VALIDATION_FAILED", "message": "Check the form. page: Not a value this field takes.", "details": { "fields": { "page": "Not a value this field takes." } }, "requestId": "18188559082372202519"}Made-up values.
PathPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
ORG | string | required | Your organisation’s code. | 3 to 20 characters |
QueryPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
page | integer | optional | 1-based page number. Overrides the header. | At least 1 |
limit | integer | optional | Page size. Overrides the header. | At least 1 |
status | string | optional | Narrows the answer: ?status=<value>, or ?status=eq:<value>. | — |
domain | string | optional | Narrows the answer: ?domain=<value>, or ?domain=eq:<value>. | — |
tag | string | optional | Narrows the answer: ?tag=<value>, or ?tag=eq:<value>. | — |
by | string | optional | Narrows the answer: ?by=<value>, or ?by=eq:<value>. | — |
health | string | optional | Narrows the answer: ?health=<value>, or ?health=eq:<value>. | — |
path | string | optional | Narrows the answer: ?path=<value>, or ?path=eq:<value>. | — |
app | string | optional | Narrows the answer: ?app=<value>, or ?app=eq:<value>. | — |
folder | string | optional | Narrows the answer: ?folder=<value>, or ?folder=eq:<value>. | — |
skipped | string | optional | Narrows the answer: ?skipped=<value>, or ?skipped=eq:<value>. | — |
new | string | optional | Narrows the answer: ?new=<value>, or ?new=eq:<value>. | — |
n | string | optional | Narrows the answer: ?n=<value>, or ?n=eq:<value>. | — |
q | string | optional | A search term. | — |
sort | string | optional | One of created, clicks, slug, then :asc or :desc (?sort=created:desc). | — |
HeadersPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
x-page-number | integer | optional | 1-based page number. | At least 1 |
x-page-size | integer | optional | Page size. | At least 1 |
In one folderPermalink
GET/api/{ORG}/folders/{folder}/links
The same list narrowed to one folder, with the same answer, paging and filters. Or stay on this address and add ?folder=<code>.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
folder | string | required | The folder’s code. | 1 to 40 characters |
AnswerPermalink
A list of Link, one page at a time: paging.
| Name | Type | Description | Allowed values |
|---|---|---|---|
id | string | The link’s id. | — |
domain | string | The short domain. | — |
slug | string | The back-half after the domain, with its path when it has one (promo/autumn). | — |
path | string | The path in front of the back-half, lower case; null for a bare name. | or null |
shortUrl | string | The whole short link. | — |
folder | string | The code of the folder the link lives in. | — |
move | LinkMove | Only on a move’s dry run (PATCH with folder and dryRun: true): what the move would change; nothing was written. | — |
inherited | string[] | The folder’s preset fields the link still follows: a change to the folder’s preset reaches them. Setting a field on the link takes it out; PATCH with inherit: [...] puts it back. | utm, params, domain, app, qr, tags, pixels |
title | string | Its name, shown above the back-half and found by the list’s search; null for none. | or null |
note | string | A note for the organisation (at most 2000 characters), never shown to visitors and not searched; null for none. | or null |
destination | string | Where it sends visitors. | — |
opens | string | The destination with the link’s UTM tags added: where a visitor lands. | — |
status | string | The stored status; DELETED only in a delete’s answer. | ACTIVE, DISABLED, EXPIRED, DELETED |
state | string | What a visitor meets now: ACTIVE, SCHEDULED (not live yet), EXPIRED, DISABLED. | ACTIVE, SCHEDULED, EXPIRED, DISABLED, DELETED |
slugChosen | boolean | The back-half was chosen; false when generated. | — |
tags | Tag[] | The link’s tags. | — |
utm | Utm | The UTM tags the redirect adds to the destination; only those set. | — |
passMode | string | Which of the visit’s own parameters pass on beside utm_ ones: FOLLOW its folder’s preset, then its own domain’s default; PASS the ones passClickIds and passNames name; NONE, whatever the domain passes (for a destination that breaks on extra parameters). Left out of a create: PASS when passClickIds or passNames is sent, else the folder’s. | FOLLOW, PASS, NONE |
passClickIds | boolean | With PASS: the ad networks’ click ids (gclid, fbclid, msclkid and the rest) pass from the visit into the destination. | — |
passNames | string[] | Other names of the visit’s parameters that pass on beside utm_ ones (ref, for one). Never a redirect’s, such as next, url or redirect_uri: those are refused. | — |
ogTitle | string | The preview title unfurlers show; null for none. | or null |
ogDescription | string | The preview description; null for none. | or null |
ogImage | string | The preview image’s address; null for none. | or null |
liveOn | date-time | When it starts answering. | — |
expiresOn | date-time | When it expires; null for never. | or null |
endedOn | date-time | When it expired or was deleted; null while it has not. | or null |
trashedOn | date-time | When it went to the trash (a deleted link that can still be restored, POST /links/<link>/restore); null otherwise. | or null |
maxClicks | integer | The click budget; null for none. | or null |
clicks | integer | Human clicks counted so far (crawlers are counted apart). | — |
hasPassword | boolean | Visitors must give a password first. | — |
masked | boolean | The destination is shown under the short link (own domains only). | — |
trackConversions | boolean | Visitors carry brv_click to the destination. | — |
publicStats | boolean | Its public stats page is on. | — |
qrStyled | boolean | Its QR code has a saved style. | — |
health | string | Whether the destination answers, as the landing probe last found it. | UNKNOWN, HEALTHY, BROKEN |
healthReason | string | Why it is broken ("Not found (404)"); else null. | or null |
flagged | boolean | A reviewer or the safety check flagged the destination. | — |
threat | string | What it was flagged for; null when it is not. | or null |
reviewRequestedOn | date-time | When a review of the flag was asked for; null when none was. | or null |
createdBy | string | Who made it, by name ("Support" for Brevily’s support team); null when the account is gone. | or null |
createdOn | date-time | When it was made. | — |
updatedOn | date-time | When it last changed; null when it never has. | or null |
Fields of move
| Name | Type | Description | Allowed values |
|---|---|---|---|
edits | integer | The link edits the move uses: 1 when any field changes, else 0. | — |
fields | string[] | The fields whose values the move changes. | utm, params, domain, app, qr, tags, pixels |
Fields of tags
| Name | Type | Description | Allowed values |
|---|---|---|---|
name | string | The tag as typed. | — |
kind | string | What the tag names; a bare name is CUSTOM. | PERSON, TEAM, CAMPAIGN, CHANNEL, PRODUCT, REGION, CUSTOM |
Fields of utm
| Name | Type | Description | Allowed values |
|---|---|---|---|
source | string | utm_source, added to the destination. | — |
medium | string | utm_medium, added to the destination. | — |
campaign | string | utm_campaign, added to the destination. | — |
term | string | utm_term, added to the destination. | — |
content | string | utm_content, added to the destination. | — |
ErrorsPermalink
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED |
A field, a parameter or the body is wrong; details.fields says which. |
| 401 | UNAUTHENTICATED |
No key, a key that does not match, or one expired or revoked. |
| 403 | ACCESS_DENIED |
The key lacks Links · view, or the organisation’s plan does not include it. |
| 404 | NOT_FOUND |
No organisation with that code for this key, or no such record in it. |
| 429 | RATE_LIMITED |
Too many calls: wait Retry-After seconds. |
Rate limitsPermalink
Counted with every other call of the organisation, by plan: Pricing. The answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; more on rate limits.
Type a call, a field or a guide.