The HTTP API

Use JSON endpoints with a scoped Bearer credential. Start with identity and board listing.

Core endpoints

Create a board

This is a write request. Store the returned board ID. Board creation is not idempotent: if the result is uncertain, inspect your boards before submitting another create request.

curl --fail-with-body -X POST 'https://vybsrf.com/api/boards' \
  -H "Authorization: Bearer $VYBSRF_AGENT_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"Reference study","description":"References to review"}'

Collect a reference

Replace BOARD_UUID with that board’s ID. Set VYBSRF_REQUEST_ID to a new 8–128 character operation ID before the first request. Keep that value and the request body unchanged when retrying this one operation; do not generate a new ID for a retry. A new collection should use a new key.

curl --fail-with-body -X POST 'https://vybsrf.com/api/pins' \
  -H "Authorization: Bearer $VYBSRF_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $VYBSRF_REQUEST_ID" \
  --data '{"board_id":"BOARD_UUID","kind":"reference","source_url":"https://example.org/reference","title":"Reference","note":"A candidate to review","purpose":"Reference study"}'

A reference uses a public HTTPS hostname without credentials or a custom port. Local addresses and numeric IP URLs are refused. An optional media_url identifies an image on the referenced page. Other pin targets are kind: upload with upload_intent_id, or kind: asset with image_id; provide exactly one target. Preview behavior is described by the running service’s capabilities.

Recall and pagination

curl --fail-with-body 'https://vybsrf.com/api/boards/BOARD_UUID/context?limit=12' \
  -H "Authorization: Bearer $VYBSRF_AGENT_KEY"

Board listing uses limit and offset; follow next_offset. Pin listing and context recall use limit and an opaque cursor; follow next_cursor. Do not treat a partial page as a complete board export.

Context recall accepts an optional q, a literal case-insensitive substring in title, note or purpose. It is not semantic search. Each recall scans at most 100 pins; inspect coverage and continuation even when no matches are returned. Saved recommendation memberships are separate from pins, so a board’s item_count is not a count of every collected reference.

Limits and failures

Ordinary JSON routes accept at most 32 KiB of uncompressed JSON; upload creation has a separate bound. Reference titles, notes and purposes are limited to 200, 2,000 and 500 characters. Pin idempotency keys contain 8–128 safe characters. Pagination limits differ by endpoint and by MCP tool; request small pages and follow returned continuation.