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
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" ] }'const res = await fetch("https://console.brevily.com/api/NORTHWIND/links", { method: "POST", headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, "Idempotency-Key": "4f9c1e2a-autumn", "Content-Type": "application/json", }, body: JSON.stringify({ "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" ] }),});const answer = await res.json();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: 9b2d7e10-launch-list" \ -H "Content-Type: application/json" \ -d '[ { "url": "https://www.example.com/spring", "folder": "campaigns" }, { "url": "https://www.example.com/autumn", "slug": "spring" } ]'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"}[ { "index": 0, "ok": true, "link": { "id": "01JD7Q4M2X9V8T6R5P3N1K0H7G", "domain": "go.example.com", "slug": "k8Rt2", "shortUrl": "https://go.example.com/k8Rt2", "url": "https://www.example.com/spring", "folder": "campaigns" } }, { "index": 1, "ok": false, "error": { "code": "VALIDATION_FAILED", "message": "Check the link.", "fields": { "slug": "That back-half is taken. Case does not matter." } } }]{ "code": "VALIDATION_FAILED", "message": "Check the form. url: Not a value this field takes.", "details": { "fields": { "url": "Not a value this field takes." } }, "requestId": "18188559082372202519"}Made-up values. Send your own Idempotency-Key, one per change.
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 |
|---|---|---|---|---|
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). | — |
BodyPermalink
JSON. An unknown field is refused with a 400 naming it.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
url | string | required | Where the link sends visitors. | — |
title | string | optional | The link’s name; null clears it. | or null |
note | string | optional | A note for the organisation, at most 2000 characters; null clears it. | or null |
tags | any[] | optional | The link’s tags. | or null |
expires | date-time | optional | When it expires (UTC); null for never. | or null |
maxClicks | integer | optional | The click budget; null for none. | or null |
liveOn | date-time | optional | When it starts answering; now when left out. | or null |
utm_source | string | optional | utm_source, added to the destination; null clears it. | or null |
utm_medium | string | optional | utm_medium, added to the destination; null clears it. | or null |
utm_campaign | string | optional | utm_campaign, added to the destination; null clears it. | or null |
utm_term | string | optional | utm_term, added to the destination; null clears it. | or null |
utm_content | string | optional | utm_content, added to the destination; null clears it. | or null |
ogTitle | string | optional | The preview title unfurlers show; null clears it. | or null |
ogDescription | string | optional | The preview description; null clears it. | or null |
ogImage | string | optional | The preview image’s address; null clears it. | or null |
masked | boolean | optional | The destination is shown under the short link (own domains only). | — |
passMode | string | optional | Which of the visit’s own parameters pass on: FOLLOW the folder and domain, PASS those named, NONE. | FOLLOW, PASS, NONE |
passClickIds | boolean | optional | With PASS: the ad networks’ click ids pass on. | — |
passNames | string[] | optional | With PASS: other parameter names that pass on. | — |
password | string | optional | A password visitors must give first. | — |
domain | string | optional | The short domain; the default one when left out. | — |
slug | string | optional | The back-half; drawn when left out. | — |
path | string | optional | A path in front of the back-half, like promo/autumn. | — |
generate | string | optional | How a drawn back-half is made: DOMAIN or a mode. | — |
folder | string | optional | The code of the folder to make it in; the default one when left out. | — |
inherit | string[] | optional | The folder’s fields the link takes whatever else is sent. | utm, params, domain, app, qr, tags, pixels |
trackConversions | boolean | optional | Visitors carry brv_click to the destination. | — |
deepLinkApp | string | optional | The organisation’s mobile app it opens. | — |
deepLinkPath | string | optional | The screen in the app. | — |
deepLinkFallback | string | optional | Where a visitor without the app goes. | WEB, STORE |
pixels | string[] | optional | The 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.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
folder | string | required | The 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-Keycovers 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.
| Name | Type | Description | Allowed values |
|---|---|---|---|
index | integer | Its place in the list sent, counted from 0. | — |
ok | boolean | True when the link was made. | — |
link | Link | — | |
error | LinkRefusal | Only when ok is false: why the link was not made. | — |
Fields of link
| 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 link.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 link.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 link.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. | — |
Fields of error
| Name | Type | Description | Allowed values |
|---|---|---|---|
code | string | The code one link refused this way answers, e.g. VALIDATION_FAILED. | — |
message | string | Why it was refused. | — |
fields | object | Each refused field and why; empty when the refusal names none. | — |
AnswerPermalink
Link
| 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. |
| 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.