v1

latestOpenAPI 3.0.32026-07-226744340.8 KB

Briefs

Create Brief

Create and kick off a Monitoring Brief. Returns 202 immediately — a Brief takes ~5–10 minutes; poll GET /api/v2/briefs/{id} for status and content. Requires a plan with Briefs access; metered separately from query units.

post/api/v2/briefs

Request body

scope_textstring required

One or two plain sentences: the situation, where it is, who/what is affected, and the decision it informs.

time_window'6h' | '24h' | '72h' | '7d' | '30d'

Recent window the Brief analyses.

baseline_window'7d' | '14d' | '30d'

Earlier comparison window for change detection.

audience'executive' | 'analyst' | 'operator'

depth'skim' | 'standard' | 'detailed'

countriesstring[]

ISO-3 country codes to scope the Brief.

regionsstring[]

sectorsstring[]

search_topicsstring[]

Free-text focus terms/phrases that bias retrieval.

actorsstring[]

Named actors to emphasize.

entitiesstring[]

Named people or organizations to emphasize.

locationsstring[]

Plain-English sub-country locations.

assetsstring[]

Named facilities or infrastructure.

public_linkboolean

When true, also mint a public shareable report URL.

titlestring

Optional; auto-generated from scope_text when omitted.

brief_type'monitoring_brief'

Optional; defaults to monitoring_brief, the only generally-available type.

Example request

{
  "scope_text": "Monitor Red Sea maritime disruption risk to shipping across Yemen, the Red Sea, and the Gulf of Aden.",
  "countries": [
    "YEM",
    "SAU"
  ],
  "search_topics": [
    "port congestion",
    "tanker insurance"
  ],
  "actors": [
    "Houthi",
    "Maersk"
  ]
}

Response

Brief generation started.

idstring

statusstring

brief_typestring

titlestring

created_atstring

web_urlstring

public_urlstring nullable

messagestring

Example response

{
  "status": "queued"
}