Preview Briefing On-Demand
Run a briefing on-demand from an ad-hoc prompt as a fire-and-forget job: enqueue the run and get a pending delivery handle immediately, then poll GET /v1/briefings/deliveries/{delivery_id} for the result.
POST /v1/briefings/sse), which streams the finished briefing back over SSE in the same request, this endpoint is fire-and-forget: it enqueues the run and returns immediately with a pending delivery handle. You then fetch the finished briefing by polling the delivery endpoints with the returned delivery_id.
The output comes from the same engine behind your scheduled briefings, so it matches their depth, formatting, and citations — letting you preview a briefing before committing to a schedule.
Stock Selection
Scope the run to specific stocks in either of two ways (omit both to cover the full market):stock_ids(recommended) — Internal stock UUIDs. Use the Map Tickers endpoint to convert ticker symbols to stock IDs first.tickers— Ticker symbols (e.g.["AAPL", "MSFT"]). Automatically resolved to stock IDs via the ticker mapping service. If a symbol cannot be resolved, the request returnsBRIEFING_GENERATE_FAIL.
stock_ids and tickers are provided, stock_ids takes priority.
Polling for the result
The202 response returns { delivery_id, status } with status: "pending" — the briefing is not ready yet. Poll GET /v1/briefings/deliveries/{delivery_id} until its status is terminal, then read the content from that response. status is the same field returned by Get Briefing Delivery.
previous_delivery_id
Pass the delivery_id of an earlier delivery to carry formatting and continuity from it into this run. The delivery must belong to your organization; otherwise the request returns BRIEFING_NOT_FOUND (see below).
Errors
Domain errors are returned as HTTP200 with an error.code (and payload: null), consistent with the other briefing JSON endpoints. Input-validation failures are the exception — they return HTTP 400.
Authentication
For platform API keys, optionally passuser_id (the customer_id), user_email, and user_name in the request body to select which user the briefing runs as. Ordinary organization-bound keys resolve the user from the key itself and ignore these fields.Authorizations
Body
The ad-hoc briefing prompt (used as the briefing topic), run through the briefing engine
Optional ticker symbols to scope the briefing; auto-resolved to stock_ids (stock_ids take priority). An unresolvable symbol returns BRIEFING_GENERATE_FAIL.
Optional internal stock ids to scope the briefing (preferred over tickers; no resolution needed)
Output language; auto-detected from the prompt when omitted
Data window (last 1 / 7 / 30 days, anchored at now). Defaults to daily.
daily, weekly, monthly IANA timezone (e.g. America/New_York) for the window and timestamps. Defaults to UTC.
A prior briefing delivery (that you own) to carry formatting/continuity from. Returns BRIEFING_NOT_FOUND if not owned.
User ID (customer_id) for platform API keys
User email for platform API keys
User name for platform API keys
Response
Domain error — returned with HTTP 200 and an error.code (payload null), consistent with the other briefing JSON endpoints. BRIEFING_NOT_FOUND when previous_delivery_id is not owned by the caller; BRIEFING_GENERATE_FAIL for a generic upstream/generation failure (including a tickers symbol that cannot be resolved to a stock).