API

Everything is JSON. All endpoints require authentication.

CLI

Manage searchbars and shortcuts from your terminal. Sync, import, bulk edit.

View on GitHub
Authentication

All requests require a Bearer token in the Authorization header. Create tokens from your API Tokens page.

Authorization: Bearer your_token_here

Tokens are hashed server-side. If you lose one, revoke it and create a new one. Bad or missing tokens return 401:

{ "error": "unauthorized" }
Endpoints

GET /api/v1/searchbars

List all your searchbars.

Response 200

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Searchbar",
    "slug": "my-searchbar",
    "visibility": "personal",
    "fallback_url": "https://www.google.com/search?q=%s",
    "encrypted": false,
    "bookmarks_count": 2,
    "created_at": "2026-03-09 12:00:00 UTC",
    "updated_at": "2026-03-09 14:30:00 UTC"
  }
]

GET /api/v1/searchbars/:slug

Get a searchbar and all its bookmarks. The :slug is the searchbar's slug, not its numeric ID.

Response 200

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Searchbar",
  "slug": "my-searchbar",
  "visibility": "personal",
  "fallback_url": "https://www.google.com/search?q=%s",
  "encrypted": false,
  "bookmarks_count": 2,
  "created_at": "2026-03-09 12:00:00 UTC",
  "updated_at": "2026-03-09 14:30:00 UTC",
  "bookmarks": [
    {
      "id": "1xi4gyp",
      "shortcut": "gh",
      "url": "https://github.com/search?q=%s",
      "name": "GitHub",
      "position": 0
    },
    {
      "id": "1o3bwsc",
      "shortcut": "npm",
      "url": "https://www.npmjs.com/search?q=%s",
      "name": "NPM",
      "position": 1
    }
  ]
}

Returns 404 if the slug doesn't match any of your searchbars.

PATCH /api/v1/searchbars/:slug

Update a searchbar's metadata and optionally replace all its bookmarks.

Request body

All fields are optional. If bookmarks is provided, it replaces the entire bookmark list.

{
  "name": "Updated Name",
  "visibility": "unlisted",
  "fallback_url": "https://duckduckgo.com/?q=%s",
  "bookmarks": [
    {
      "shortcut": "gh",
      "url": "https://github.com/search?q=%s",
      "name": "GitHub"
    },
    {
      "shortcut": "cal",
      "url": "https://calendar.google.com",
      "name": "Calendar"
    }
  ]
}

Response 200

Returns the updated searchbar with bookmarks, same shape as the GET response.

Fields

Field Type Notes
name string Display name
visibility string personal, unlisted, or public_access
fallback_url string Use %s for the query
encrypted boolean Toggle encryption flag
bookmarks array Replaces all bookmarks. Each needs shortcut and url. name is optional. Position is array order.
Notes
  • Searchbar slugs must be lowercase alphanumeric with hyphens. 1-60 characters.
  • Bookmark shortcuts must be lowercase alphanumeric with colons and hyphens. Must be unique within a searchbar.
  • The API only exposes your own searchbars. You can't access other users' data even if their searchbars are public.
  • When syncing bookmarks via PATCH, any existing bookmarks whose shortcuts aren't in the incoming array are deleted.
  • Encrypted searchbars store ciphertext in the url field. The API returns it as-is. Encryption and decryption happen client-side.
  • The API is versioned at /api/v1. Breaking changes will get a new version.