Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Use the Bri HTTP API

The HTTP API is JSON over HTTPS at https://bri.fyi. The generated API Reference tab is the machine-readable contract; this page covers the workflows and security rules that are easiest to get wrong.

Authenticate requests

The Authorization header carries the full API key:
curl -sS \
  -H "Authorization: Bearer $BRI_API_KEY" \
  https://bri.fyi/api/notes
Keys have independent permissions:
  • read can list and read accessible resources, including note versions.
  • write can create, update, delete, restore, invite, and dismiss.
  • read_write combines both and is required for API-key browser sessions.
The server checks the required permission on every operation. A write-only key cannot read, and a read-only key cannot publish or restore.

Create and read a note

The create endpoint returns a compact result with the stable ID and generated slug:
curl -sS -X POST \
  -H "Authorization: Bearer $BRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Release notes",
    "content": "# Shipped\n\nPublished from a service.",
    "visibility": "public",
    "expiresInDays": 30
  }' \
  https://bri.fyi/api/notes
The expiration field accepts a positive number of days up to 30, or null for no expiration. The title is trimmed to 120 characters; empty Markdown is rejected.
The list endpoint returns complete note records in a data envelope:
curl -sS \
  -H "Authorization: Bearer $BRI_API_KEY" \
  'https://bri.fyi/api/notes?state=active'
Pass state=deleted to inspect soft-deleted notes. Active reads best-effort expire due notes before returning.

Update, delete, and restore

The stable note ID is the correct identifier for mutations. Changing a title may change the slug, but it does not change the ID.
curl -sS -X PATCH \
  -H "Authorization: Bearer $BRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated title",
    "content": "# Updated\n\nNew content.",
    "visibility": "private",
    "expiresInDays": null
  }' \
  https://bri.fyi/api/notes/by-id/<note-id>
Every successful content update stores a version snapshot. The same PATCH route accepts the softDelete or permanentDelete action; permanent deletion removes the note and its stored versions.
Restoring a deleted note through the note-by-ID route is a signed-in web-session operation. API-key integrations should restore a version through the version endpoint:
curl -sS -X PATCH \
  -H "Authorization: Bearer $BRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"restore","versionId":"<version-id>"}' \
  https://bri.fyi/api/notes/by-id/<note-id>/versions

Read version history

The version endpoint lists metadata by default and returns one full snapshot when versionId is supplied:
curl -sS \
  -H "Authorization: Bearer $BRI_API_KEY" \
  'https://bri.fyi/api/notes/by-id/<note-id>/versions?limit=50'

curl -sS \
  -H "Authorization: Bearer $BRI_API_KEY" \
  'https://bri.fyi/api/notes/by-id/<note-id>/versions?versionId=<version-id>'
The limit is clamped between 1 and 100 and defaults to 50. Version reads require an active, unexpired note and read permission.

Read public content

The JSON read route is useful for integrations:
curl -sS https://bri.fyi/api/public/notes/<username>/<slug>
The Markdown route returns text/markdown and works well with downloaders:
curl -fsS \
  -H "Authorization: Bearer $BRI_API_KEY" \
  https://bri.fyi/api/notes/<username>/<slug>/markdown \
  -o note.md
Public notes need no key. Private notes require the owner, an invited user, or an owner API key with read permission; inaccessible notes return 404 rather than leaking their existence.

Quick links and sharing

The quick-link endpoints use the same permission model:
GET    /api/quick-links
POST   /api/quick-links
PATCH  /api/quick-links/<link-id>
DELETE /api/quick-links/<link-id>
Create a short redirect with an HTTP or HTTPS target:
curl -sS -X POST \
  -H "Authorization: Bearer $BRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"docs","targetUrl":"https://bri.fyi/docs","label":"Bri docs"}' \
  https://bri.fyi/api/quick-links
The sharing endpoints invite a username to a note or link and return invitation summaries:
curl -sS -X POST \
  -H "Authorization: Bearer $BRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"note","id":"<note-id>","inviteeUsername":"teammate"}' \
  https://bri.fyi/api/invitations

curl -sS \
  -H "Authorization: Bearer $BRI_API_KEY" \
  https://bri.fyi/api/invitations/summary

AI questions and MCP

The ask endpoint streams a plain-text answer grounded in one readable note:
curl -N -sS -X POST \
  -H "Content-Type: application/json" \
  -d '{"question":"What are the launch risks?"}' \
  https://bri.fyi/api/notes/<username>/<slug>/ask
The MCP endpoint is https://bri.fyi/mcp. Use GET for discovery and stateless JSON POST requests with a bearer key; the full tool list and confirmation guidance are in the MCP guide.

Errors and safe retries

An error response is a small JSON object with an error field. Check the status code before reading data.
  • 400 means the body, ID, title, content, or parameter is invalid.
  • 401 means the key is missing, malformed, revoked, or invalid.
  • 403 means the key lacks the required permission or ownership.
  • 404 means the resource is unavailable to the caller.
  • 409 means a quick-link key already exists.
  • 413 means the AI request body is too large.
  • 429 means the AI request rate limit is active; honor Retry-After.
  • 5xx means a transient or server configuration failure; retry with backoff when the operation is safe.
The API is not idempotent by default. Use a client-generated reconciliation record around create operations, and do not blindly retry a publish request after an unknown network failure without checking the resulting note list.
Powered byHolocron