Links › Change a link
Links
Change a link
PATCH/api/{ORG}/links/{link}Permalink
Answers the Link.
- Permission
- Links · edit
- Plan
- Plans that include the API: Pricing
- Retry
- Safe with an
Idempotency-Key
Example request
curl -X PATCH "https://console.brevily.com/api/NORTHWIND/links/01JC6Y8QH2M4ZK7T9VRW3XNB5D" \ -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", "clearPassword": false, "status": "ACTIVE", "trackConversions": false, "publicStats": false, "folder": "example", "inherit": [ "utm" ], "dryRun": false, "confirm": "example" }'const res = await fetch("https://console.brevily.com/api/NORTHWIND/links/01JC6Y8QH2M4ZK7T9VRW3XNB5D", { method: "PATCH", 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", "clearPassword": false, "status": "ACTIVE", "trackConversions": false, "publicStats": false, "folder": "example", "inherit": [ "utm" ], "dryRun": false, "confirm": "example" }),});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. 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 |
link | string | required | — |
HeadersPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
content-type | string | optional | — |
BodyPermalink
JSON. An unknown field is refused with a 400 naming it.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
url | string | optional | A new destination. | — |
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. | — |
clearPassword | boolean | optional | True removes the password. | — |
status | string | optional | Switch the link on or off. | ACTIVE, DISABLED |
trackConversions | boolean | optional | Visitors carry brv_click to the destination. | — |
publicStats | boolean | optional | Its public stats page is on. Also needs Analytics · Share. | — |
folder | string | optional | The code of the folder to move it to. | — |
inherit | string[] | optional | The folder’s fields to take back from its folder. | utm, params, domain, app, qr, tags, pixels |
dryRun | boolean | optional | With folder: true writes nothing and answers move. | — |
confirm | any | optional | With folder: { edits }, the count a dry run answered. | — |
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 · edit, 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.
Type a call, a field or a guide.