Folders › Get a folder

Folders

Get a folder

GET/api/{ORG}/folders/{folder}Permalink

Answers the Folder.

Permission
Links · view
Plan
Plans that include the API: Pricing
Retry
Safe: a read changes nothing

Example request

bash
curl "https://console.brevily.com/api/NORTHWIND/folders/general" \  -H "x-api-key: brv_ak_7Fq2Lw9xK3" \  -H "x-api-secret: $BREVILY_SECRET"

Example answer

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

Made-up values.

PathPermalink

Path parameters
NameTypeRequiredDescriptionAllowed values
ORGstringrequiredYour organisation’s code.3 to 20 characters
folderstringrequired1 to 40 characters

AnswerPermalink

Folder

Answer fields
NameTypeDescriptionAllowed values
idstringThe folder’s id.—
codestringThe folder’s address in the API (/folders/<code>/links): lower-case letters, digits and single dashes.—
namestringThe folder’s name.—
isDefaultbooleanThe organisation’s default folder: where a link goes when none is named. It can be renamed, never deleted.—
linksintegerLinks in it (deleted ones not counted).—
utmFolderUtmThe UTM tags a new link starts with; null for none.or null
paramsFolderPassParamsWhich 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
domainstringThe short domain a new link starts on; null for none.or null
appFolderAppThe mobile app a new link opens; null for none.or null
qranyThe QR code style a new link starts with (fg, bg, moduleShape, logo: SMALL, MEDIUM or LARGE, quietZone); null for none.—
tagsFolderTag[]The tags a new link starts with.—
pixelsstring[]The ad pixels a new link fires, by integration id.—
locksstring[]The locked preset fields.utm, params, domain, app, qr, tags, pixels
restrictedbooleanWhether 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.—
createdOndate-timeWhen it was made.—
updatedOndate-timeWhen it last changed; null when it never has.or null
impactPresetImpactWhat the change does to the folder’s existing links.—
presetJobPresetJobA folder’s preset change as the background job applies it.or null
Fields of utm
Fields of utm
NameTypeDescriptionAllowed values
sourcestringutm_source, copied into a new link.—
mediumstringutm_medium, copied into a new link.—
campaignstringutm_campaign, copied into a new link.—
termstringutm_term, copied into a new link.—
contentstringutm_content, copied into a new link.—
Fields of params
Fields of params
NameTypeDescriptionAllowed values
clickIdsbooleanAd click ids (gclid, fbclid, msclkid and the rest) pass from the visit.—
namesstring[]Other names of the visit’s parameters that pass (never a redirect’s, such as next or url).—
Fields of app
Fields of app
NameTypeDescriptionAllowed values
appIdstringThe organisation’s mobile app.—
pathstringThe screen in the app.—
fallbackstringWhere a visitor without the app goes.WEB, STORE
Fields of tags
Fields of tags
NameTypeDescriptionAllowed values
namestringThe tag as typed.—
kindstringWhat the tag names.PERSON, TEAM, CAMPAIGN, CHANNEL, PRODUCT, REGION, CUSTOM
Fields of impact
Fields of impact
NameTypeDescriptionAllowed values
followingintegerLinks that follow a field the change touches.—
ownintegerLinks with their own value for a touched field the folder does not lock: kept unless force is true.—
forcedintegerLinks with their own value for a field the change locks: the lock forces the folder’s value onto them.—
editsintegerLinks that will change, one link edit each (links keeping their own value cost nothing).—
Fields of presetJob
Fields of presetJob
NameTypeDescriptionAllowed values
idstringThe job’s id.—
statusstringPENDING while links are still being updated.PENDING, DONE, FAILED
fieldsstring[]The preset fields the job applies.utm, params, domain, app, qr, tags, pixels
forcebooleanWhether links with their own value were included.—
reservedintegerDestination edits set aside for it.—
changedintegerLinks updated so far.—
skippedintegerLinks left alone because the edits reserved ran out.—
refundedintegerReserved edits given back (when the job ended).—
errorstringWhy a failed job stopped.or null
createdOndate-timeWhen the change was made.—
finishedOndate-timeWhen the job ended; null while it runs.or null

ErrorsPermalink

Errors
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.