DocsReference

Endpoints

Every endpoint, its parameters, a curl and a sample response.

Every endpoint, with its parameters, a request you can paste into a terminal and a sample response. All paths are relative to https://api.webbites.io/v1/api, all requests carry Authorization: Bearer …, and everything is JSON in and JSON out.

GET /bookmarks GET /bookmarks/:id POST /bookmarks GET /usage GET /webhooks POST /webhooks DELETE /webhooks/:id POST /webhooks/:id/test

Bookmarks

Read and write the library itself.

GET/bookmarks

List your bookmarks, newest first. Page with nextBefore.

Parameters

Name	In	Required	Description
`limit`	query	no	max rows (default 50)
`before`	query	no	cursor from a previous nextBefore
`tag`	query	no	only bookmarks with this tag
`type`	query	no	website, article, image, textNote…
`q`	query	no	full-text search

Request

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

Name	In	Required	Description
`id`	path	yes	bookmark id

Request

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

Name	In	Required	Description
`url`	body	yes	the page to save
`tags`	body	no	comma separated
`note`	body	no	free-text note

Request

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" }

Account

What your plan allows and what you have spent.

GET/usage

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

Request

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 } } }

Webhooks

GET/webhooks

Your webhooks and the events they can subscribe to.

Request

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

Name	In	Required	Description
`url`	body	yes	https endpoint to POST to
`events`	body	no	comma separated, default bookmark.saved
`description`	body	no	a label for you

Request

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

Name	In	Required	Description
`id`	path	yes	webhook id

Request

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

Name	In	Required	Description
`id`	path	yes	webhook id

Request

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

Response

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

The generated reference

This page is the hand-written version. The OpenAPI document is generated from the server itself — point your client generator at it, or read it when you want the exact schema of a field rather than an example of it.