Tags

List, rename, merge and delete a workspace's tags.

Tags are created when you add them to links. Here you see how many links have each, and rename or delete them across every link at once. Changing tags needs permission to edit links.

Every path below starts with https://bgum.me/api/v1/workspaces/{workspaceId}. Send your API key in the Authorization header as described in the API overview.

Operation	Method and path
List tags	GET `/tags`
Rename a tag	PATCH `/tags/{tag}`
Delete a tag	DELETE `/tags/{tag}`

List tags

GET /tags

Lists the workspace's tags by name, with how many links have each.

Full path: /api/v1/workspaces/{workspaceId}/tags
API key scope: links:read
Role needed: Viewer or above

Path parameters

Name	Type	Required	Description
`workspaceId`	string	Yes	Your workspace ID, from Settings → Workspace.

Example request

curl

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

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/tags`, {
  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);

Python

import os
import requests

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

Response

200 OK · application/json

JSON

[
  {
    "name": "newsletter",
    "linkCount": 31
  },
  {
    "name": "spring",
    "linkCount": 12
  }
]

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.

Rename a tag

PATCH /tags/{tag}

Renames a tag on every link that has it. Renaming it to the name of another tag merges the two.

Full path: /api/v1/workspaces/{workspaceId}/tags/{tag}
API key scope: links:write
Role needed: Manager or above

Path parameters

Name	Type	Required	Description
`workspaceId`	string	Yes	Your workspace ID, from Settings → Workspace.
`tag`	string	Yes	The tag's name (case doesn't matter), URL-encoded: a / is %2F.

Request body

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

Name	Type	Required	Description
`name`	string	Yes	The new name, up to 50 characters.

Example request

curl

curl -X PATCH "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/tags/newsletter" \
  -H "Authorization: Bearer $BGL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Newsletter"
}'

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/tags/newsletter`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Newsletter"
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const data = await res.json();
console.log(data);

Python

import os
import requests

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

Response

200 OK · application/json

JSON

{
  "tag": {
    "name": "Newsletter",
    "linkCount": 31
  },
  "merged": false
}

Good to know

merged is true when another tag already had the new name: links with either now have that one, and the old tag is gone.

Errors

Status	Code	Meaning
404	`tag.not_found`	No tag with that name in this workspace.
422	`tag.name_required`	The new name is empty.
422	`tags.too_long`	A tag is longer than 50 characters.

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 tag

DELETE /tags/{tag}

Deletes a tag and takes it off every link. The links stay.

Full path: /api/v1/workspaces/{workspaceId}/tags/{tag}
API key scope: links:write
Role needed: Manager or above

Path parameters

Name	Type	Required	Description
`workspaceId`	string	Yes	Your workspace ID, from Settings → Workspace.
`tag`	string	Yes	The tag's name (case doesn't matter), URL-encoded: a / is %2F.

Example request

curl

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

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/tags/newsletter`, {
  method: "DELETE",
  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);

Python

import os
import requests

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

Response

200 OK · application/json

JSON

{
  "links": 12
}

Good to know

links is how many links had the tag.

Errors

Status	Code	Meaning
404	`tag.not_found`	No tag with that name in this workspace.

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.

Something missing or unclear? Tell us and we'll improve this page.