bookmarks

bookmarks.farfield.systems

A curated link list with OpenGraph metadata fetched server-side on save. Each bookmark carries a public flag — only public ones appear in the public API or on the public HTML index. Admin-only fields such as adminNotes are never returned publicly.

Screenshot of the Farfield bookmarks UI — Bookmarks admin table in the logged-in state. The read API returns public rows only and is token-gated.

Authentication

The read endpoints require a bearer token — send the read key as Authorization: Bearer <token> or X-API-Key; the write key is also accepted. They return public bookmarks only. /status stays public, and responses still send Access-Control-Allow-Origin: *.

JSON API

GET /api/bookmarks

{ "bookmarks": [Bookmark, …] } — public only; strong ETag

GET /api/bookmarks/{id}

Bookmark — 404 if missing or private; strong ETag

GET /status

{ "service": "bookmarks", "ok": true, "bookmarks": N }

Write endpoints (POST /api/bookmarks, PUT /api/bookmarks/{id}, DELETE /api/bookmarks/{id}) require an API key and the BOOKMARKS_API_KEY environment variable must be set on the service.

The HTML admin UI lives under /admin and is gated by the shared password.

Record Shape

Bookmark

{
  "id": "string",
  "url": "https://…",
  "title": "string",
  "description": "string",
  "category": "string",
  "public": true,
  "cid": "bafk…",
  "ogTitle": "string?",
  "ogDescription": "string?",
  "ogImage": "string?",
  "ogSiteName": "string?",
  "ogType": "string?",
  "metaAuthor": "string?",
  "favicon": "string?",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}