Links

Create a link

POST /links

Creates a short link. Leave out alias to get a random back-half. Each new link uses one of the organisation's monthly allowance.

Full path

/api/v1/workspaces/{workspaceId}/links

API key scope

links:write

Role needed

Manager or above

Path parameters

Headers

Request body

JSON (Content-Type: application/json). Leave out fields you don't need.

Example request

curl -X POST "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/links" \
  -H "Authorization: Bearer $BGL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "destinationUrl": "https://example.com/spring-sale",
  "alias": "spring-sale",
  "title": "Spring sale",
  "tags": [
    "email",
    "spring"
  ],
  "campaignId": "aiQrz1XgekFP"
}'

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/links`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "destinationUrl": "https://example.com/spring-sale",
    "alias": "spring-sale",
    "title": "Spring sale",
    "tags": [
      "email",
      "spring"
    ],
    "campaignId": "aiQrz1XgekFP"
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

import os
import requests
import uuid

res = requests.post(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/links",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "destinationUrl": "https://example.com/spring-sale",
        "alias": "spring-sale",
        "title": "Spring sale",
        "tags": ["email", "spring"],
        "campaignId": "aiQrz1XgekFP",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

201 Created · application/json

{
  "id": "ZiZihoWXe3as",
  "shortUrl": "https://bgum.me/spring-sale",
  "domain": "bgum.me",
  "alias": "spring-sale",
  "isCustomAlias": true,
  "destinationUrl": "https://example.com/spring-sale",
  "title": "Spring sale",
  "description": null,
  "notes": null,
  "status": "Active",
  "state": "Active",
  "startsAt": null,
  "endsAt": null,
  "redirectType": "Found",
  "passwordProtected": false,
  "tags": [
    "email",
    "spring"
  ],
  "campaignId": "aiQrz1XgekFP",
  "version": 1,
  "createdAt": "2026-10-14T22:49:34.114896+00:00",
  "updatedAt": "2026-10-14T22:49:34.114896+00:00",
  "totalClicks": 0,
  "blocked": false,
  "trackConversions": false,
  "folderId": "q5Tz0aLmW2xd",
  "routing": null,
  "maxClicks": null,
  "clickLimitReached": false,
  "expiredRedirectUrl": null
}

Good to know

• Returns 201 with a Location header for a new link. A repeat with the same Idempotency-Key returns 200 and the original link.
• When the monthly allowance is used up the response is 429 with a Retry-After header (seconds) and resetsAt in the body.
• The account that owns the key must have confirmed its email address.
• routing has three optional parts. rules: up to 20, checked in order; the first rule whose conditions all match sends the visitor to its destinationUrl. Each rule needs at least one of countries (two-letter codes such as AU), devices (ios, android, windows, macos, other) or languages (the browser's preferred language, such as en). split: 2 to 5 destinations with whole-number weights from 1 to 1,000, sharing everyone no rule matched; the same visitor keeps getting the same one. app: iosUrl and androidUrl, your app's own link (myapp://…), an Android intent: link or an https link; phones try the app first and fall back to the web destination. See Smart routing in the help centre.
• Each rule and split destination has an id (up to 12 lower-case letters and digits). Leave it out and one is made up. Send the ids back when you change routing, so analytics keep counting each rule and destination as the same one.
• Every destination in routing is checked like destinationUrl, including the safety check. Smart routing needs the Business plan; maxClicks needs Pro or above.

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.

List links

GET /links

Lists the workspace's links one page at a time: newest first, or best match first when searching. Archived links are left out unless you ask for them with state=Archived.

Full path

/api/v1/workspaces/{workspaceId}/links

API key scope

links:read

Role needed

Viewer or above

Path parameters

Query parameters

Example request

curl "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/links?search=spring&state=Active&pageSize=50" \
  -H "Authorization: Bearer $BGL_API_KEY"

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/links?search=spring&state=Active&pageSize=50`, {
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

import os
import requests

res = requests.get(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/links?search=spring&state=Active&pageSize=50",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

{
  "items": [
    {
      "id": "ZiZihoWXe3as",
      "shortUrl": "https://bgum.me/spring-sale",
      "domain": "bgum.me",
      "alias": "spring-sale",
      "isCustomAlias": true,
      "destinationUrl": "https://example.com/spring-sale",
      "title": "Spring sale",
      "description": null,
      "notes": null,
      "status": "Active",
      "state": "Active",
      "startsAt": null,
      "endsAt": null,
      "redirectType": "Found",
      "passwordProtected": false,
      "tags": [
        "email",
        "spring"
      ],
      "campaignId": "aiQrz1XgekFP",
      "version": 1,
      "createdAt": "2026-10-14T22:49:34.114896+00:00",
      "updatedAt": "2026-10-14T22:49:34.114896+00:00",
      "totalClicks": 0,
      "blocked": false,
      "trackConversions": false,
      "folderId": "q5Tz0aLmW2xd",
      "routing": null,
      "maxClicks": null,
      "clickLimitReached": false,
      "expiredRedirectUrl": null
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}

Good to know

• total is the number of matching links across all pages. Keep requesting the next page until you've seen total items or a page comes back empty.
• To count the links a filter matches (for example before a bulk action), ask for pageSize=1 and read total.

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.

Get a link

GET /links/{linkId}

Returns one link, including its total clicks.

Full path

/api/v1/workspaces/{workspaceId}/links/{linkId}

API key scope

links:read

Role needed

Viewer or above

Path parameters

Example request

curl "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/links/ZiZihoWXe3as" \
  -H "Authorization: Bearer $BGL_API_KEY"

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/links/ZiZihoWXe3as`, {
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

import os
import requests

res = requests.get(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/links/ZiZihoWXe3as",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

{
  "id": "ZiZihoWXe3as",
  "shortUrl": "https://bgum.me/spring-sale",
  "domain": "bgum.me",
  "alias": "spring-sale",
  "isCustomAlias": true,
  "destinationUrl": "https://example.com/spring-sale",
  "title": "Spring sale",
  "description": null,
  "notes": null,
  "status": "Active",
  "state": "Active",
  "startsAt": null,
  "endsAt": null,
  "redirectType": "Found",
  "passwordProtected": false,
  "tags": [
    "email",
    "spring"
  ],
  "campaignId": "aiQrz1XgekFP",
  "version": 1,
  "createdAt": "2026-10-14T22:49:34.114896+00:00",
  "updatedAt": "2026-10-14T22:49:34.114896+00:00",
  "totalClicks": 0,
  "blocked": false,
  "trackConversions": false,
  "folderId": "q5Tz0aLmW2xd",
  "routing": null,
  "maxClicks": null,
  "clickLimitReached": false,
  "expiredRedirectUrl": null
}

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.

Change a link

PATCH /links/{linkId}

Changes only the fields you send. Changing a link never uses your monthly allowance. The redirect changes straight away.

Full path

/api/v1/workspaces/{workspaceId}/links/{linkId}

API key scope

links:write

Role needed

Manager or above

Path parameters

Request body

JSON (Content-Type: application/json). Leave out fields you don't need.

Example request

curl -X PATCH "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/links/ZiZihoWXe3as" \
  -H "Authorization: Bearer $BGL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "destinationUrl": "https://example.com/spring-sale-2026",
  "expectedVersion": 1
}'

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/links/ZiZihoWXe3as`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "destinationUrl": "https://example.com/spring-sale-2026",
    "expectedVersion": 1
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

import os
import requests

res = requests.patch(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/links/ZiZihoWXe3as",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    json={
        "destinationUrl": "https://example.com/spring-sale-2026",
        "expectedVersion": 1,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

{
  "id": "ZiZihoWXe3as",
  "shortUrl": "https://bgum.me/spring-sale",
  "domain": "bgum.me",
  "alias": "spring-sale",
  "isCustomAlias": true,
  "destinationUrl": "https://example.com/spring-sale-2026",
  "title": "Spring sale",
  "description": null,
  "notes": null,
  "status": "Active",
  "state": "Active",
  "startsAt": null,
  "endsAt": null,
  "redirectType": "Found",
  "passwordProtected": false,
  "tags": [
    "email",
    "spring"
  ],
  "campaignId": "aiQrz1XgekFP",
  "version": 2,
  "createdAt": "2026-10-14T22:49:34.114896+00:00",
  "updatedAt": "2026-10-15T01:12:40.5862714+00:00",
  "totalClicks": 0,
  "blocked": false,
  "trackConversions": false,
  "folderId": "q5Tz0aLmW2xd",
  "routing": null,
  "maxClicks": null,
  "clickLimitReached": false,
  "expiredRedirectUrl": null
}

Good to know

• The back-half and domain can't be changed: create a new link instead, so printed or shared copies never change meaning.
• Each change adds a version; the link page in the app shows the history.
• routing has three optional parts. rules: up to 20, checked in order; the first rule whose conditions all match sends the visitor to its destinationUrl. Each rule needs at least one of countries (two-letter codes such as AU), devices (ios, android, windows, macos, other) or languages (the browser's preferred language, such as en). split: 2 to 5 destinations with whole-number weights from 1 to 1,000, sharing everyone no rule matched; the same visitor keeps getting the same one. app: iosUrl and androidUrl, your app's own link (myapp://…), an Android intent: link or an https link; phones try the app first and fall back to the web destination. See Smart routing in the help centre.
• Each rule and split destination has an id (up to 12 lower-case letters and digits). Leave it out and one is made up. Send the ids back when you change routing, so analytics keep counting each rule and destination as the same one.
• Every destination in routing is checked like destinationUrl, including the safety check. Smart routing needs the Business plan; maxClicks needs Pro or above.

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.

Delete a link

DELETE /links/{linkId}

Deletes the link. It stops redirecting straight away and its back-half is never reused, so old copies can't be taken over.

Full path

/api/v1/workspaces/{workspaceId}/links/{linkId}

API key scope

links:write

Role needed

Manager or above

Path parameters

Example request

curl -X DELETE "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/links/ZiZihoWXe3as" \
  -H "Authorization: Bearer $BGL_API_KEY"

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/links/ZiZihoWXe3as`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
// 204 No Content: nothing to read.

import os
import requests

res = requests.delete(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/links/ZiZihoWXe3as",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
# 204 No Content: nothing to read.

Response

204 No Content

Good to know

• Deleting doesn't give back the monthly allowance. To stop a link temporarily, PATCH its status to Paused instead.

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.

Create links in bulk

POST /links/bulk

Creates many links in one request (Business). Each link is created on its own: one bad row doesn't stop the others.

Full path

/api/v1/workspaces/{workspaceId}/links/bulk

API key scope

links:write

Role needed

Manager or above

Plan

Needs bulk operations in your plan (compare plans)

Path parameters

Headers

Request body

JSON (Content-Type: application/json). Leave out fields you don't need.

Example request

curl -X POST "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/links/bulk" \
  -H "Authorization: Bearer $BGL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "links": [
    {
      "destinationUrl": "https://example.com/a",
      "title": "Page A"
    },
    {
      "destinationUrl": "https://example.com/b",
      "alias": "page-b"
    }
  ]
}'

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/links/bulk`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "links": [
      {
        "destinationUrl": "https://example.com/a",
        "title": "Page A"
      },
      {
        "destinationUrl": "https://example.com/b",
        "alias": "page-b"
      }
    ]
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

import os
import requests
import uuid

res = requests.post(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/links/bulk",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "links": [
            {
                "destinationUrl": "https://example.com/a",
                "title": "Page A",
            },
            {
                "destinationUrl": "https://example.com/b",
                "alias": "page-b",
            },
        ],
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

{
  "rows": [
    {
      "line": 1,
      "destination": "https://example.com/a",
      "outcome": "created",
      "shortUrl": "https://bgum.me/a2ruepj",
      "linkId": "ZGqD6yhrCyac",
      "error": null,
      "sourceShortUrl": null,
      "note": null
    },
    {
      "line": 2,
      "destination": "https://example.com/b",
      "outcome": "failed",
      "shortUrl": null,
      "linkId": null,
      "error": "“page-b” is already in use on this domain. Try another back-half.",
      "sourceShortUrl": null,
      "note": null
    }
  ],
  "created": 1,
  "alreadyCreated": 0,
  "failed": 1,
  "notAttempted": 0
}

Good to know

• outcome is created, already created (from an earlier attempt with the same key), failed (error says why) or not attempted.
• If the monthly allowance runs out part-way, the remaining rows are not attempted. Retry later with the same Idempotency-Key to finish the batch without duplicates.

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.

Change many links

POST /links/bulk-actions

Moves, tags, pauses, resumes, sets or removes stop times on, or deletes many links in one request: the links you list, or every link matching a filter. Works on every plan.

Full path

/api/v1/workspaces/{workspaceId}/links/bulk-actions

API key scope

links:write

Role needed

Manager or above

Path parameters

Request body

JSON (Content-Type: application/json). Leave out fields you don't need.

Example request

curl -X POST "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/links/bulk-actions" \
  -H "Authorization: Bearer $BGL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "pause",
  "filter": {
    "search": "spring",
    "state": "Active"
  },
  "expectedCount": 23
}'

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/links/bulk-actions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "action": "pause",
    "filter": {
      "search": "spring",
      "state": "Active"
    },
    "expectedCount": 23
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

import os
import requests

res = requests.post(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/links/bulk-actions",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    json={
        "action": "pause",
        "filter": {
            "search": "spring",
            "state": "Active",
        },
        "expectedCount": 23,
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

{
  "action": "pause",
  "matched": 23,
  "changed": 22,
  "unchanged": 0,
  "failed": [
    {
      "linkId": "ZiZihoWXe3as",
      "code": "link.blocked",
      "message": "This link was disabled after an abuse report or a safety check, so it can't be changed. Contact support if you think this is a mistake."
    }
  ]
}

Good to know

• unchanged counts links already as asked, such as pausing a paused link. failed lists links that weren't changed and why: listed IDs not found in this workspace (link.not_found), links disabled by a safety check (link.blocked), a link that would get more than 20 tags, or a stop time before its start time.
• Links are changed in batches of 200. If someone changes one of a batch at the same moment, that batch is left as it was and its links are listed in failed with link.version_conflict: send them again.
• Pausing, resuming, stop times and deleting reach the short links straight away and are added to each link's history.

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.

Check a back-half

GET /aliases/availability

Says whether a back-half is free on a domain, without reserving it.

Full path

/api/v1/workspaces/{workspaceId}/aliases/availability

API key scope

links:write

Role needed

Manager or above

Path parameters

Query parameters

Example request

curl "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/aliases/availability?alias=summer-sale" \
  -H "Authorization: Bearer $BGL_API_KEY"

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/aliases/availability?alias=summer-sale`, {
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

import os
import requests

res = requests.get(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/aliases/availability?alias=summer-sale",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

{
  "alias": "summer-sale",
  "available": true
}

Good to know

• When the back-half isn't allowed, available is false and reason and code explain why, e.g. {"alias":"admin","available":false,"reason":"That back-half is reserved. Try another.","code":"alias.reserved"}. Someone else can still take a free back-half before you create the link.

Errors

Any request can also return the general errors: 401 for a missing or wrong key, 403 for a missing scope or plan feature, 404 for an unknown workspace and 429 when you're sending too fast.