Skip to content

Doc & URL Blips API

POST /api/briefblip/blip.php

Fetches (or accepts) content, extracts a cited brief, and stores it at a permanent, shareable slug. Streamed as Server-Sent Events.

Auth: anonymous (10/hour and 30/day per network) or X-Briefblip-Key (no limit) — plus a site-wide daily cap that can trip independently of any one caller.

{ "url": "https://example.com/article" }
or 
{ "text": "raw text, max 60,000 chars", "title": "optional" }

Exactly one of url or text — never both, never neither.

{"stage":"validating"}
{"stage":"fetching","domain":"example.com"}   // url kind only
{"stage":"extracting","chars":4213}
{"stage":"composing"}
{"done":true,"slug":"a1B2c3D4e5","url":"https://briefblip.com/b/a1B2c3D4e5",
 "kind":"url","brief":{ "title":"...", "tl_dr":"...",
   "key_points":[{"point":"...","quote":"...","quote_verified":true}],
   "facts_figures":["..."], "who_should_care":"...",
   "reading_time_min":4 },
 "cost":{"usd":0.0,"input_tokens":0,"output_tokens":0,"model":"..."}}

The HTTP status is always 200 once streaming starts

A failure partway through arrives as a terminal {"error":"..."} event on the stream, not as a different HTTP status code. Check for that event — don't rely on response.ok.

Pre-stream errors (real HTTP status, before any events are sent): 400 bad input · 429 rate limit (hourly or daily) · 503 doc/URL blips temporarily switched off, or the site-wide daily cap has been reached.

Notes: URL fetching is restricted to public web addresses (no private networks, no internal hosts), capped at ~4 MB / 15 seconds. Extracted text under ~200 characters isn't enough to work with and fails the blip.

GET /api/briefblip/view.php — public path /b/<slug>

Reads back a completed blip. Fully public, no rate limit.

Request: ?slug=<10-character code>, optionally &format=json.

Response: 200 HTML (the branded permalink page) by default, or JSON with &format=json:

{ "slug":"...", "url":"...", "kind":"url", "source_url":"...",
  "source_domain":"...", "brief":{ }, "model":"...", "created_at":"...",
  "view_count":0 }

A slug that's unknown, still processing, failed, or has been taken down all return the same 404 — there's no way to distinguish "never existed" from "removed."

GET /api/briefblip/og.php

Renders the share-card image (1200×630 PNG) used when a /b/<slug> link is pasted into Slack, iMessage, or social media. Not meant to be called directly — referenced automatically from the permalink page's meta tags. Rate-limited (150/hour per network); returns 404 for any slug view.php wouldn't show.