Folders › List the organisation’s folders
Folders
List the organisation’s folders
GET/api/{ORG}/foldersPermalink
The organisation’s folders: the default one first, then by name.
- 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/folders" \ -H "x-api-key: brv_ak_7Fq2Lw9xK3" \ -H "x-api-secret: $BREVILY_SECRET"const res = await fetch("https://console.brevily.com/api/NORTHWIND/folders", { headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, },});const answer = await res.json();Example answer
[ { "id": "01JC6Y8QH2M4ZK7T9VRW3XNB5D", "code": "example", "name": "example", "isDefault": false, "links": 1, "utm": { "source": "example", "medium": "example", "campaign": "example", "term": "example", "content": "example" }, "params": { "clickIds": false, "names": [ "example" ] }, "domain": "go.example.com", "app": { "appId": "01JC6Y8QH2M4ZK7T9VRW3XNB5D", "path": "example", "fallback": "WEB" }, "qr": "example", "tags": [ { "name": "example", "kind": "PERSON" } ], "pixels": [ "example" ], "locks": [ "utm" ], "restricted": false, "createdOn": "2026-11-05T09:41:00Z", "updatedOn": "2026-11-05T09:41:00Z", "impact": { "following": 1, "own": 1, "forced": 1, "edits": 1 }, "presetJob": { "id": "01JC6Y8QH2M4ZK7T9VRW3XNB5D", "status": "PENDING", "fields": [ "utm" ], "force": false, "reserved": 1, "changed": 1, "skipped": 0, "refunded": 1, "error": "example", "createdOn": "2026-11-05T09:41:00Z", "finishedOn": "2026-11-05T09:41:00Z" } }]{ "code": "VALIDATION_FAILED", "message": "Check the form. (root): Not a value this field takes.", "details": { "fields": { "(root)": "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 |
AnswerPermalink
A list of Folder, one page at a time: paging.
| Name | Type | Description | Allowed values |
|---|---|---|---|
id | string | The folder’s id. | — |
code | string | The folder’s address in the API (/folders/<code>/links): lower-case letters, digits and single dashes. | — |
name | string | The folder’s name. | — |
isDefault | boolean | The organisation’s default folder: where a link goes when none is named. It can be renamed, never deleted. | — |
links | integer | Links in it (deleted ones not counted). | — |
utm | FolderUtm | The UTM tags a new link starts with; null for none. | or null |
params | FolderPassParams | 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. | or null |
domain | string | The short domain a new link starts on; null for none. | or null |
app | FolderApp | The mobile app a new link opens; null for none. | or null |
qr | any | The QR code style a new link starts with (fg, bg, moduleShape, logo: SMALL, MEDIUM or LARGE, quietZone); null for none. | — |
tags | FolderTag[] | The tags a new link starts with. | — |
pixels | string[] | The ad pixels a new link fires, by integration id. | — |
locks | string[] | The locked preset fields. | utm, params, domain, app, qr, tags, pixels |
restricted | 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. | — |
createdOn | date-time | When it was made. | — |
updatedOn | date-time | When it last changed; null when it never has. | or null |
impact | PresetImpact | What the change does to the folder’s existing links. | — |
presetJob | PresetJob | A folder’s preset change as the background job applies it. | or null |
Fields of utm
| Name | Type | Description | Allowed values |
|---|---|---|---|
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. | — |
Fields of params
| Name | Type | Description | Allowed values |
|---|---|---|---|
clickIds | boolean | Ad click ids (gclid, fbclid, msclkid and the rest) pass from the visit. | — |
names | string[] | Other names of the visit’s parameters that pass (never a redirect’s, such as next or url). | — |
Fields of app
| Name | Type | Description | Allowed values |
|---|---|---|---|
appId | string | The organisation’s mobile app. | — |
path | string | The screen in the app. | — |
fallback | string | Where a visitor without the app goes. | WEB, STORE |
Fields of tags
| Name | Type | Description | Allowed values |
|---|---|---|---|
name | string | The tag as typed. | — |
kind | string | What the tag names. | PERSON, TEAM, CAMPAIGN, CHANNEL, PRODUCT, REGION, CUSTOM |
Fields of impact
| Name | Type | Description | Allowed values |
|---|---|---|---|
following | integer | Links that follow a field the change touches. | — |
own | integer | Links with their own value for a touched field the folder does not lock: kept unless force is true. | — |
forced | integer | Links with their own value for a field the change locks: the lock forces the folder’s value onto them. | — |
edits | integer | Links that will change, one link edit each (links keeping their own value cost nothing). | — |
Fields of presetJob
| Name | Type | Description | Allowed values |
|---|---|---|---|
id | string | The job’s id. | — |
status | string | PENDING while links are still being updated. | PENDING, DONE, FAILED |
fields | string[] | The preset fields the job applies. | utm, params, domain, app, qr, tags, pixels |
force | boolean | Whether links with their own value were included. | — |
reserved | integer | Destination edits set aside for it. | — |
changed | integer | Links updated so far. | — |
skipped | integer | Links left alone because the edits reserved ran out. | — |
refunded | integer | Reserved edits given back (when the job ended). | — |
error | string | Why a failed job stopped. | or null |
createdOn | date-time | When the change was made. | — |
finishedOn | date-time | When the job ended; null while it runs. | or null |
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.