Links › Create a link

Links

Create a link

POST/api/{ORG}/linksPermalink

One link object answers 201 and the link. A list of 1 to 100 link objects (FOLDER_BULK on the plan) makes each on its own, as one link is made: in the folder it names, else the default one (on /folders/{folder}/links, that folder). The answer is 200 and a list in the order sent: { index, ok: true, link } for each link made, { index, ok: false, error: { code, message, fields } } for each refused. One refused link stops none of the others.

Permission
Links · create
Plan
Plans that include the API: Pricing
Retry
Safe with an Idempotency-Key

Example request

bash
curl -X POST "https://console.brevily.com/api/NORTHWIND/links" \  -H "x-api-key: brv_ak_7Fq2Lw9xK3" \  -H "x-api-secret: $BREVILY_SECRET" \  -H "Idempotency-Key: 4f9c1e2a-autumn" \  -H "Content-Type: application/json" \  -d '{    "url": "https://www.example.com/sale/autumn",    "title": "example",    "note": "example",    "tags": [      "example"    ],    "expires": "2026-11-05T09:41:00Z",    "maxClicks": 1,    "liveOn": "2026-11-05T09:41:00Z",    "utm_source": "example",    "utm_medium": "example",    "utm_campaign": "example",    "utm_term": "example",    "utm_content": "example",    "ogTitle": "example",    "ogDescription": "example",    "ogImage": "example",    "masked": false,    "passMode": "FOLLOW",    "passClickIds": false,    "passNames": [      "example"    ],    "password": "example",    "domain": "go.example.com",    "slug": "example",    "path": "example",    "generate": "example",    "folder": "example",    "inherit": [      "utm"    ],    "trackConversions": false,    "deepLinkApp": "example",    "deepLinkPath": "example",    "deepLinkFallback": "WEB",    "pixels": [      "example"    ]  }'

Example answer

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

Made-up values. Send your own Idempotency-Key, one per change.

PathPermalink

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

QueryPermalink

Query parameters
NameTypeRequiredDescriptionAllowed values
statusstringoptionalNarrows the answer: ?status=<value>, or ?status=eq:<value>.—
domainstringoptionalNarrows the answer: ?domain=<value>, or ?domain=eq:<value>.—
tagstringoptionalNarrows the answer: ?tag=<value>, or ?tag=eq:<value>.—
bystringoptionalNarrows the answer: ?by=<value>, or ?by=eq:<value>.—
healthstringoptionalNarrows the answer: ?health=<value>, or ?health=eq:<value>.—
pathstringoptionalNarrows the answer: ?path=<value>, or ?path=eq:<value>.—
appstringoptionalNarrows the answer: ?app=<value>, or ?app=eq:<value>.—
folderstringoptionalNarrows the answer: ?folder=<value>, or ?folder=eq:<value>.—
skippedstringoptionalNarrows the answer: ?skipped=<value>, or ?skipped=eq:<value>.—
newstringoptionalNarrows the answer: ?new=<value>, or ?new=eq:<value>.—
nstringoptionalNarrows the answer: ?n=<value>, or ?n=eq:<value>.—
qstringoptionalA search term.—
sortstringoptionalOne of created, clicks, slug, then :asc or :desc (?sort=created:desc).—

BodyPermalink

JSON. An unknown field is refused with a 400 naming it.

Body fields
NameTypeRequiredDescriptionAllowed values
urlstringrequiredWhere the link sends visitors.—
titlestringoptionalThe link’s name; null clears it.or null
notestringoptionalA note for the organisation, at most 2000 characters; null clears it.or null
tagsany[]optionalThe link’s tags.or null
expiresdate-timeoptionalWhen it expires (UTC); null for never.or null
maxClicksintegeroptionalThe click budget; null for none.or null
liveOndate-timeoptionalWhen it starts answering; now when left out.or null
utm_sourcestringoptionalutm_source, added to the destination; null clears it.or null
utm_mediumstringoptionalutm_medium, added to the destination; null clears it.or null
utm_campaignstringoptionalutm_campaign, added to the destination; null clears it.or null
utm_termstringoptionalutm_term, added to the destination; null clears it.or null
utm_contentstringoptionalutm_content, added to the destination; null clears it.or null
ogTitlestringoptionalThe preview title unfurlers show; null clears it.or null
ogDescriptionstringoptionalThe preview description; null clears it.or null
ogImagestringoptionalThe preview image’s address; null clears it.or null
maskedbooleanoptionalThe destination is shown under the short link (own domains only).—
passModestringoptionalWhich of the visit’s own parameters pass on: FOLLOW the folder and domain, PASS those named, NONE.FOLLOW, PASS, NONE
passClickIdsbooleanoptionalWith PASS: the ad networks’ click ids pass on.—
passNamesstring[]optionalWith PASS: other parameter names that pass on.—
passwordstringoptionalA password visitors must give first.—
domainstringoptionalThe short domain; the default one when left out.—
slugstringoptionalThe back-half; drawn when left out.—
pathstringoptionalA path in front of the back-half, like promo/autumn.—
generatestringoptionalHow a drawn back-half is made: DOMAIN or a mode.—
folderstringoptionalThe code of the folder to make it in; the default one when left out.—
inheritstring[]optionalThe folder’s fields the link takes whatever else is sent.utm, params, domain, app, qr, tags, pixels
trackConversionsbooleanoptionalVisitors carry brv_click to the destination.—
deepLinkAppstringoptionalThe organisation’s mobile app it opens.—
deepLinkPathstringoptionalThe screen in the app.—
deepLinkFallbackstringoptionalWhere a visitor without the app goes.WEB, STORE
pixelsstring[]optionalThe ad pixels it fires.—

In one folderPermalink

POST/api/{ORG}/folders/{folder}/links

The same call: each link goes into that folder unless it names its own, and a link naming another folder is refused on its own. An unknown folder answers 404. Or stay on this address and send folder in each link’s body.

Path parameters of the folder’s address
NameTypeRequiredDescriptionAllowed values
folderstringrequiredThe folder’s code.1 to 40 characters

Many links in one callPermalink

Send a JSON list of 1 to 100 links instead of one, each exactly one link’s body, its own folder included. Each link is made or refused on its own, in the order sent: one refused link stops none of the others.

  • The answer is 200 and a result for each link, in the order sent: { index, ok: true, link } for one made, { index, ok: false, error: { code, message, fields } } for one refused.
  • A list of N links counts as N calls against the rate limit; links past it are refused on their own, as RATE_LIMITED.
  • One Idempotency-Key covers the whole list: a retry answers the same results.
  • A list needs a plan with many links in one call (Pricing). Without it, or with more than 100 links, the answer is 400 and nothing is made.
List answer fields
NameTypeDescriptionAllowed values
indexintegerIts place in the list sent, counted from 0.—
okbooleanTrue when the link was made.—
linkLink—
errorLinkRefusalOnly when ok is false: why the link was not made.—
Fields of link
Fields of link
NameTypeDescriptionAllowed values
idstringThe link’s id.—
domainstringThe short domain.—
slugstringThe back-half after the domain, with its path when it has one (promo/autumn).—
pathstringThe path in front of the back-half, lower case; null for a bare name.or null
shortUrlstringThe whole short link.—
folderstringThe code of the folder the link lives in.—
moveLinkMoveOnly on a move’s dry run (PATCH with folder and dryRun: true): what the move would change; nothing was written.—
inheritedstring[]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
titlestringIts name, shown above the back-half and found by the list’s search; null for none.or null
notestringA note for the organisation (at most 2000 characters), never shown to visitors and not searched; null for none.or null
destinationstringWhere it sends visitors.—
opensstringThe destination with the link’s UTM tags added: where a visitor lands.—
statusstringThe stored status; DELETED only in a delete’s answer.ACTIVE, DISABLED, EXPIRED, DELETED
statestringWhat a visitor meets now: ACTIVE, SCHEDULED (not live yet), EXPIRED, DISABLED.ACTIVE, SCHEDULED, EXPIRED, DISABLED, DELETED
slugChosenbooleanThe back-half was chosen; false when generated.—
tagsTag[]The link’s tags.—
utmUtmThe UTM tags the redirect adds to the destination; only those set.—
passModestringWhich 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
passClickIdsbooleanWith PASS: the ad networks’ click ids (gclid, fbclid, msclkid and the rest) pass from the visit into the destination.—
passNamesstring[]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.—
ogTitlestringThe preview title unfurlers show; null for none.or null
ogDescriptionstringThe preview description; null for none.or null
ogImagestringThe preview image’s address; null for none.or null
liveOndate-timeWhen it starts answering.—
expiresOndate-timeWhen it expires; null for never.or null
endedOndate-timeWhen it expired or was deleted; null while it has not.or null
trashedOndate-timeWhen it went to the trash (a deleted link that can still be restored, POST /links/<link>/restore); null otherwise.or null
maxClicksintegerThe click budget; null for none.or null
clicksintegerHuman clicks counted so far (crawlers are counted apart).—
hasPasswordbooleanVisitors must give a password first.—
maskedbooleanThe destination is shown under the short link (own domains only).—
trackConversionsbooleanVisitors carry brv_click to the destination.—
publicStatsbooleanIts public stats page is on.—
qrStyledbooleanIts QR code has a saved style.—
healthstringWhether the destination answers, as the landing probe last found it.UNKNOWN, HEALTHY, BROKEN
healthReasonstringWhy it is broken ("Not found (404)"); else null.or null
flaggedbooleanA reviewer or the safety check flagged the destination.—
threatstringWhat it was flagged for; null when it is not.or null
reviewRequestedOndate-timeWhen a review of the flag was asked for; null when none was.or null
createdBystringWho made it, by name ("Support" for Brevily’s support team); null when the account is gone.or null
createdOndate-timeWhen it was made.—
updatedOndate-timeWhen it last changed; null when it never has.or null
Fields of link.move
Fields of link.move
NameTypeDescriptionAllowed values
editsintegerThe link edits the move uses: 1 when any field changes, else 0.—
fieldsstring[]The fields whose values the move changes.utm, params, domain, app, qr, tags, pixels
Fields of link.tags
Fields of link.tags
NameTypeDescriptionAllowed values
namestringThe tag as typed.—
kindstringWhat the tag names; a bare name is CUSTOM.PERSON, TEAM, CAMPAIGN, CHANNEL, PRODUCT, REGION, CUSTOM
Fields of link.utm
Fields of link.utm
NameTypeDescriptionAllowed values
sourcestringutm_source, added to the destination.—
mediumstringutm_medium, added to the destination.—
campaignstringutm_campaign, added to the destination.—
termstringutm_term, added to the destination.—
contentstringutm_content, added to the destination.—
Fields of error
Fields of error
NameTypeDescriptionAllowed values
codestringThe code one link refused this way answers, e.g. VALIDATION_FAILED.—
messagestringWhy it was refused.—
fieldsobjectEach refused field and why; empty when the refusal names none.—

AnswerPermalink

Link

Answer fields
NameTypeDescriptionAllowed values
idstringThe link’s id.—
domainstringThe short domain.—
slugstringThe back-half after the domain, with its path when it has one (promo/autumn).—
pathstringThe path in front of the back-half, lower case; null for a bare name.or null
shortUrlstringThe whole short link.—
folderstringThe code of the folder the link lives in.—
moveLinkMoveOnly on a move’s dry run (PATCH with folder and dryRun: true): what the move would change; nothing was written.—
inheritedstring[]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
titlestringIts name, shown above the back-half and found by the list’s search; null for none.or null
notestringA note for the organisation (at most 2000 characters), never shown to visitors and not searched; null for none.or null
destinationstringWhere it sends visitors.—
opensstringThe destination with the link’s UTM tags added: where a visitor lands.—
statusstringThe stored status; DELETED only in a delete’s answer.ACTIVE, DISABLED, EXPIRED, DELETED
statestringWhat a visitor meets now: ACTIVE, SCHEDULED (not live yet), EXPIRED, DISABLED.ACTIVE, SCHEDULED, EXPIRED, DISABLED, DELETED
slugChosenbooleanThe back-half was chosen; false when generated.—
tagsTag[]The link’s tags.—
utmUtmThe UTM tags the redirect adds to the destination; only those set.—
passModestringWhich 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
passClickIdsbooleanWith PASS: the ad networks’ click ids (gclid, fbclid, msclkid and the rest) pass from the visit into the destination.—
passNamesstring[]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.—
ogTitlestringThe preview title unfurlers show; null for none.or null
ogDescriptionstringThe preview description; null for none.or null
ogImagestringThe preview image’s address; null for none.or null
liveOndate-timeWhen it starts answering.—
expiresOndate-timeWhen it expires; null for never.or null
endedOndate-timeWhen it expired or was deleted; null while it has not.or null
trashedOndate-timeWhen it went to the trash (a deleted link that can still be restored, POST /links/<link>/restore); null otherwise.or null
maxClicksintegerThe click budget; null for none.or null
clicksintegerHuman clicks counted so far (crawlers are counted apart).—
hasPasswordbooleanVisitors must give a password first.—
maskedbooleanThe destination is shown under the short link (own domains only).—
trackConversionsbooleanVisitors carry brv_click to the destination.—
publicStatsbooleanIts public stats page is on.—
qrStyledbooleanIts QR code has a saved style.—
healthstringWhether the destination answers, as the landing probe last found it.UNKNOWN, HEALTHY, BROKEN
healthReasonstringWhy it is broken ("Not found (404)"); else null.or null
flaggedbooleanA reviewer or the safety check flagged the destination.—
threatstringWhat it was flagged for; null when it is not.or null
reviewRequestedOndate-timeWhen a review of the flag was asked for; null when none was.or null
createdBystringWho made it, by name ("Support" for Brevily’s support team); null when the account is gone.or null
createdOndate-timeWhen it was made.—
updatedOndate-timeWhen it last changed; null when it never has.or null
Fields of move
Fields of move
NameTypeDescriptionAllowed values
editsintegerThe link edits the move uses: 1 when any field changes, else 0.—
fieldsstring[]The fields whose values the move changes.utm, params, domain, app, qr, tags, pixels
Fields of tags
Fields of tags
NameTypeDescriptionAllowed values
namestringThe tag as typed.—
kindstringWhat the tag names; a bare name is CUSTOM.PERSON, TEAM, CAMPAIGN, CHANNEL, PRODUCT, REGION, CUSTOM
Fields of utm
Fields of utm
NameTypeDescriptionAllowed values
sourcestringutm_source, added to the destination.—
mediumstringutm_medium, added to the destination.—
campaignstringutm_campaign, added to the destination.—
termstringutm_term, added to the destination.—
contentstringutm_content, added to the destination.—

ErrorsPermalink

Errors
Status Code When
400 VALIDATION_FAILED A field, a parameter or the body is wrong; details.fields says which.
400 IDEMPOTENCY_KEY_INVALID The Idempotency-Key is longer than 255 characters.
401 UNAUTHENTICATED No key, a key that does not match, or one expired or revoked.
403 ACCESS_DENIED The key lacks Links · create, 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.
409 CONFLICT
409 IDEMPOTENCY_IN_FLIGHT The first call with this Idempotency-Key is still running.
413 PAYLOAD_TOO_LARGE
415 UNSUPPORTED_MEDIA
422 IDEMPOTENCY_MISMATCH The same Idempotency-Key was sent with a different request.
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.