API

This example opts out of the optional clarification step. If you omit clarify and receive HTTP 200 with needs_clarification, the body carries clarification_kind (identity or scope), identity_answer_enabled (always true), options (display labels), angles (each label paired with a complete sharpened query that preserves the original query's entities, e.g. "Argentina vs Spain" -> "Argentina vs Spain for the recent football matchup"), and original_query. Identity questions may have no preset options. To answer one, re-POST the original query with clarify: {answer: {kind: "identity", text: "The company at every.to"}}. The complete description (1–1000 Unicode characters) is stored separately from the research query as unverified user intent. Typed scope uses kind "scope" and a short focus phrase. Invalid or unsupported answers return 422 invalid_request before reservation; keep the answer editable. Comparison identity corrections are currently unsupported. Do not put a website into a scope answer. Re-POST the same original query with clarify: {angle: <picked angle's query>} - not the label itself; an angle that does not preserve the original query's entities (such as re-posting a bare label) is rejected, and the original query is dispatched instead. To repeat or save an existing report, use source_search_id with an optional matching query; it cannot be combined with clarify. Access and eligibility are checked server-side, and the private intent snapshot is inherited without appearing in responses or URLs. Set force_fresh to true to always start new research. Source-based requests also run fresh. Eligible requests may receive an independent copy of recent public-topic research at the normal price, with the original research date retained; a 202 response can already have status complete. Poll responses include research_started_at for the original research time; created_at is when your independent report was created. Older reports may have no research_started_at. Omitted or false force_fresh keeps the same request identity; changing it to true requires a new idempotency key. Optional context (up to 500 characters) says who or what the query means when you already know: the subject's handles or a one-line description. It is an unverified hint for finding the right subject, never instructions; a handle the web does not confirm is not used. A request with context always runs fresh, cannot be combined with source_search_id or a --competitors query, and is part of the request identity, so different context needs a new idempotency key. New 202 responses additively echo query - the accepted research query, sharpened or original; idempotent replay responses omit it. Poll after HTTP 202 to retrieve the report, including when it is already complete. Keep the same idempotency key only when retrying this exact request after a timeout or lost response. Generate a new key for every intentional new search, including a later run of the same query.

Tip: pipe step 1 through jq -r .search_id to capture the id for step 2. Treat progress cursors as opaque; append delta in order, and replace local progress when reset is true.

next_window_at is when the first report arrives. A schedule made from source_search_id sends that report right away, free, and first_delivery says how that went: sent, already_sent, in_progress, not_sent or unknown. Scheduling the same report again returns the existing schedule with existing: true and retries any destination that did not get it. A query is never matched to an existing schedule.

Choosing a channel joins it first, and a 400 with reason says why Slack refused. Turning off the last destination is refused with 422; turn the other one on first.

If the calendar briefs watch is no longer available, resume answers 409. Choose a calendar instead, below.

Switching cancels the scheduled briefs for the old calendar. Briefs already researched are sent only if their meeting is on the new calendar, and the new calendar's meetings appear after its next sync. Choosing the current calendar again returns changed false and restarts briefs paused because that calendar was unavailable. Errors: 400 when calendar_id is missing or not one GET lists; 404 when no Google Calendar is connected; 409 with reconnect_url when Google has not given Last30Days your calendar list (open it in a browser to go back through Google, then try again); 409 without it when the connection changed during the switch (read again and retry); 502 when Google could not be read.