Folders

Organise links into folders, up to 3 levels deep.

A folder holds links, and other folders up to 3 levels deep. A link is in one folder at most: set folderId when you create or change a link, or move many with Change many links. Changing folders 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 folders	GET `/folders`
Create a folder	POST `/folders`
Get a folder	GET `/folders/{folderId}`
Rename or move a folder	PATCH `/folders/{folderId}`
Delete a folder	DELETE `/folders/{folderId}`

List folders

GET /folders

Lists every folder in the workspace in tree order: each folder followed by its subfolders, by name.

Full path: /api/v1/workspaces/{workspaceId}/folders
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/folders" \
  -H "Authorization: Bearer $BGL_API_KEY"

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/folders`, {
  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']}/folders",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

JSON

[
  {
    "id": "q5Tz0aLmW2xd",
    "name": "Spring",
    "parentId": "Hc81LrVq0aTe",
    "path": "Marketing / Spring",
    "depth": 2,
    "linkCount": 14,
    "createdAt": "2026-10-15T03:12:44.1932+00:00"
  }
]

Good to know

linkCount counts links directly in the folder, leaving out archived ones and those in subfolders. depth is 1 at the top level.

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 a folder

POST /folders

Creates a folder at the top level or inside another one.

Full path: /api/v1/workspaces/{workspaceId}/folders
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.

Request body

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

Name	Type	Required	Description
`name`	string	Yes	Up to 100 characters. Unique among the folders in the same place (case doesn't matter).
`parentId`	string	No	The folder to create it in. Leave out for the top level.

Example request

curl

curl -X POST "https://bgum.me/api/v1/workspaces/$WORKSPACE_ID/folders" \
  -H "Authorization: Bearer $BGL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring",
  "parentId": "Hc81LrVq0aTe"
}'

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/folders`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Spring",
    "parentId": "Hc81LrVq0aTe"
  }),
});
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.post(
    f"https://bgum.me/api/v1/workspaces/{os.environ['WORKSPACE_ID']}/folders",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    json={
        "name": "Spring",
        "parentId": "Hc81LrVq0aTe",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

201 Created · application/json

JSON

{
  "id": "q5Tz0aLmW2xd",
  "name": "Spring",
  "parentId": "Hc81LrVq0aTe",
  "path": "Marketing / Spring",
  "depth": 2,
  "linkCount": 14,
  "createdAt": "2026-10-15T03:12:44.1932+00:00"
}

Errors

Status	Code	Meaning
422	`folder.name_required`	The folder has no name.
422	`folder.name_too_long`	The name is longer than 100 characters.
409	`folder.name_taken`	Another folder in the same place already has that name (case doesn't matter).
404	`folder.not_found`	No folder with that ID in this workspace.
409	`folder.too_deep`	The folder would be more than 3 levels deep, or would leave one of its folders more than 3 levels deep.
409	`folder.too_many`	The workspace already has 500 folders.

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 folder

GET /folders/{folderId}

Returns one folder with its path and link count.

Full path: /api/v1/workspaces/{workspaceId}/folders/{folderId}
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.
`folderId`	string	Yes	The folder's ID, as returned when it was created or listed.

Example request

curl

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

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/folders/q5Tz0aLmW2xd`, {
  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']}/folders/q5Tz0aLmW2xd",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

JSON

{
  "id": "q5Tz0aLmW2xd",
  "name": "Spring",
  "parentId": "Hc81LrVq0aTe",
  "path": "Marketing / Spring",
  "depth": 2,
  "linkCount": 14,
  "createdAt": "2026-10-15T03:12:44.1932+00:00"
}

Errors

Status	Code	Meaning
404	`folder.not_found`	No folder with that ID 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.

Rename or move a folder

PATCH /folders/{folderId}

Renames a folder, moves it (with everything in it) into another folder or to the top level, or both.

Full path: /api/v1/workspaces/{workspaceId}/folders/{folderId}
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.
`folderId`	string	Yes	The folder's ID, as returned when it was created or listed.

Request body

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

Name	Type	Required	Description
`name`	string	No	New name.
`parentId`	string	No	Moves the folder into this folder.
`moveToTop`	boolean	No	true moves the folder to the top level.

Example request

curl

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

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/folders/q5Tz0aLmW2xd`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.BGL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Spring 2027"
  }),
});
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']}/folders/q5Tz0aLmW2xd",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    json={
        "name": "Spring 2027",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

JSON

{
  "id": "q5Tz0aLmW2xd",
  "name": "Spring 2027",
  "parentId": "Hc81LrVq0aTe",
  "path": "Marketing / Spring 2027",
  "depth": 2,
  "linkCount": 14,
  "createdAt": "2026-10-15T03:12:44.1932+00:00"
}

Good to know

A folder can't move into itself or one of its own folders, or anywhere that would make its deepest folder more than 3 levels down.

Errors

Status	Code	Meaning
404	`folder.not_found`	No folder with that ID in this workspace.
422	`folder.name_required`	The folder has no name.
422	`folder.name_too_long`	The name is longer than 100 characters.
409	`folder.name_taken`	Another folder in the same place already has that name (case doesn't matter).
409	`folder.too_deep`	The folder would be more than 3 levels deep, or would leave one of its folders more than 3 levels deep.
409	`folder.into_itself`	A folder can't move into itself or one of its own folders.

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 folder

DELETE /folders/{folderId}

Deletes a folder. Its links and folders move up a level (to the top level if it was a top-level folder); no link is deleted.

Full path: /api/v1/workspaces/{workspaceId}/folders/{folderId}
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.
`folderId`	string	Yes	The folder's ID, as returned when it was created or listed.

Example request

curl

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

JavaScript

const res = await fetch(`https://bgum.me/api/v1/workspaces/${process.env.WORKSPACE_ID}/folders/q5Tz0aLmW2xd`, {
  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']}/folders/q5Tz0aLmW2xd",
    headers={
        "Authorization": f"Bearer {os.environ['BGL_API_KEY']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())

Response

200 OK · application/json

JSON

{
  "linksMoved": 14,
  "foldersMoved": 1
}

Good to know

A moved folder whose name its new neighbours already use gets the deleted folder's name in front, such as "Spring - Email".

Errors

Status	Code	Meaning
404	`folder.not_found`	No folder with that ID 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.