---
title: "Create a bookmark or folder"
method: POST
path: "/browser-bookmarks"
tags: ["browser-bookmarks"]
---

# Create a bookmark or folder

`POST /browser-bookmarks`

## Request

- Base URL: `https://api.focusbear.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.focusbear.io/browser-bookmarks`
- Auth: HTTP bearer

Retry-safe with client_id: a live item with the same client_id is returned unchanged.

## Request body

- CreateBrowserBookmarkDto
  - `kind` 'bookmark' | 'folder', required
  - `title` string, required: May be empty, as in Chrome. Stored encrypted.
  - `url` string: Required for a bookmark, rejected for a folder. Any scheme. Stored encrypted.
  - `parent_id` string, uuid, nullable: Folder to create the item in; omit or null for the top level
  - `position` number: Sort key among siblings; omitted means after the last sibling
  - `client_id` string: The client's own id for the item (e.g. Chrome's node GUID). Unique among the user's live items.

## Response `201`

- BrowserBookmarkResponseDto
  - `id` string, uuid, required
  - `parent_id` string, uuid, nullable, required: Null for a top-level item
  - `kind` 'bookmark' | 'folder', required
  - `client_id` string, nullable, required
  - `title` string, required
  - `url` string, nullable, required: Null exactly when kind is folder
  - `position` number, required: Sort key among siblings; order by position, then id
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `deleted_at` string, date-time, nullable, required: Set on a deleted item; only the sync feed returns deleted items

## Other responses

- `400`: Body is { code, message }; code is one of: browser_bookmark_url_required, browser_bookmark_url_not_allowed_on_folder
- `409`: Body is { code, message }; code is one of: browser_bookmark_parent_not_found, browser_bookmark_parent_not_folder, browser_bookmark_limit_reached

---

[API](https://skmtc.dev/focusbear/apis/focusbear-api.md) - [All operations](https://skmtc.dev/focusbear/apis/focusbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/focusbear/apis/focusbear-api/revisions/3a83a3b9a811?raw)