Links › Restore a link from the trash
Links
Restore a link from the trash
POST/api/{ORG}/links/{link}/restorePermalink
Takes a link out of the trash, back to what it was before it was deleted (active, disabled or expired), with every value it had, in its folder. Free, and it never needs room in the plan. 404 when the link is not in the trash.
- Permission
- Links · delete
- 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/01JC6Y8QH2M4ZK7T9VRW3XNB5D/restore" \ -H "x-api-key: brv_ak_7Fq2Lw9xK3" \ -H "x-api-secret: $BREVILY_SECRET" \ -H "Idempotency-Key: 4f9c1e2a-autumn"const res = await fetch("https://console.brevily.com/api/NORTHWIND/links/01JC6Y8QH2M4ZK7T9VRW3XNB5D/restore", { method: "POST", headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, "Idempotency-Key": "4f9c1e2a-autumn", },});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. status: Not a value this field takes.", "details": { "fields": { "status": "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 | — |
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). | — |
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 · delete, 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.