WebBites API

Read and save bookmarks from your own scripts, apps and automations.

Full OpenAPI reference

Overview

Base URL

https://api.webbites.io/v1/api

Authentication

Every request carries an API key created below (or in Settings → Developer).

Authorization: Bearer wb_live_…

Rate limits

Plan	Per minute	Per month
free	60	1,000
plus	300	20,000
ultra	1,000	100,000

Over the limit you get a 429. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Endpoints

GET/bookmarks

List your bookmarks, newest first. Page with `nextBefore`.

Parameters

limit — max rows (default 50)
before — cursor from a previous nextBefore
tag — only bookmarks with this tag
type — website, article, image, textNote…
q — full-text search

Example

curl https://api.webbites.io/v1/api/bookmarks \
  -H "Authorization: Bearer $WEBBITES_KEY"

Response

{
  "bookmarks": [
    { "id": "abc123", "url": "https://example.com", "title": "Example", "type": "website", "tags": ["docs"], "createdAt": "2026-01-02T10:00:00.000Z" }
  ],
  "nextBefore": "2026-01-02T10:00:00.000Z"
}

GET/bookmarks/:id

One bookmark with its summary, tags, note, screenshot and metadata.

Parameters

id (path) — bookmark id

Example

curl https://api.webbites.io/v1/api/bookmarks/abc123 \
  -H "Authorization: Bearer $WEBBITES_KEY"

Response

{ "id": "abc123", "url": "https://example.com", "title": "Example", "description": "…", "type": "website", "tags": ["docs"], "note": "", "summary": "…", "image": "https://…", "screenshot": "https://…", "favicon": "https://…", "createdAt": "…" }

POST/bookmarks

Save a URL. Screenshot, summary and auto-tags are generated in the background; a webhook fires when it is done.

Body

url — the page to save
tags — comma separated
note — free-text note

Example

curl -X POST https://api.webbites.io/v1/api/bookmarks \
  -H "Authorization: Bearer $WEBBITES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Response

{ "id": "abc123", "url": "https://example.com", "status": "processing" }

GET/usage

Your plan, its limits and what you have used this month, per key.

Example

curl https://api.webbites.io/v1/api/usage \
  -H "Authorization: Bearer $WEBBITES_KEY"

Response

{ "tier": "plus", "limits": { "perMinute": 300, "perMonth": 20000 }, "usage": { "month": 412, "total": 9031, "byKey": { "wb_live_…": 412 } } }

GET/webhooks

Your webhooks and the events they can subscribe to.

Example

curl https://api.webbites.io/v1/api/webhooks \
  -H "Authorization: Bearer $WEBBITES_KEY"

Response

{ "webhooks": [ { "id": "wh_1", "url": "https://example.com/hook", "events": ["bookmark.saved"], "description": "", "active": true, "failureCount": 0, "lastStatus": 200, "lastDeliveredAt": "…", "secret": "whsec_…" } ], "events": ["bookmark.saved"] }

POST/webhooks

Body

url — https endpoint to POST to
events — comma separated, default bookmark.saved
description — a label for you

Example

curl -X POST https://api.webbites.io/v1/api/webhooks \
  -H "Authorization: Bearer $WEBBITES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Response

{ "id": "wh_1", "url": "https://example.com/hook", "events": ["bookmark.saved"], "active": true, "secret": "whsec_…" }

DELETE/webhooks/:id

Remove a webhook.

Parameters

id (path) — webhook id

Example

curl -X DELETE https://api.webbites.io/v1/api/webhooks/abc123 \
  -H "Authorization: Bearer $WEBBITES_KEY"

Response

{ "ok": true }

POST/webhooks/:id/test

Send a sample delivery and report the status your endpoint answered with.

Body

id (path) — webhook id

Example

curl -X POST https://api.webbites.io/v1/api/webhooks/abc123/test \
  -H "Authorization: Bearer $WEBBITES_KEY"

Response

{ "ok": true, "status": 200 }

Webhooks

Register a URL with POST /webhooks (below, or with a key) and WebBites will POST to it every time a bookmark is saved. Events: bookmark.saved.

Payload

{
  "id": "dlv_…",
  "event": "bookmark.saved",
  "createdAt": "2026-01-02T10:00:00.000Z",
  "data": {
    "id": "abc123", "url": "https://example.com", "title": "Example", "description": "…",
    "type": "website", "tags": ["docs"], "note": "", "summary": "…",
    "image": "https://…", "screenshot": "https://…", "favicon": "https://…",
    "createdAt": "2026-01-02T10:00:00.000Z"
  }
}

Headers

X-WebBites-Event — the event name
X-WebBites-Delivery — unique delivery id (use it to de-duplicate retries)
X-WebBites-Signature — sha256=<hex HMAC-SHA256(secret, raw body)>

Verify the signature (Node)

import crypto from 'node:crypto'

// rawBody must be the untouched request body (a Buffer or string), not re-serialised JSON.
function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return expected.length === signatureHeader.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}