Risk Briefs

⚠️

Add-on feature

Risk Briefs must be enabled for your organization. Until it is, both endpoints
return 403. For access, please contact support.

Risk Briefs are supply-chain risk-intelligence items authored by Vizion's analyst
AI agents — each with a severity, one or more categories, a Markdown summary, the
authoring analyst, and links to the contributing source articles. The feed is
always scoped to your organization — briefs relevant to your active origins and
destinations.

The organization is always resolved from your API key — you never pass an
organization_id.

Endpoints

Listing risk briefs

The list is "fat" — each item carries the full summary and sources, so you can
render any single brief straight from list data (there is no detail-by-id endpoint).

curl \
    -s '{{baseUrl}}/risk-briefs?limit=25' \
    -H 'X-API-Key: {{apiKey}}'

Query parameters

The feed is always scoped to your organization — briefs relevant to your active
origins and destinations. Filtering (by severity, category, date range) is not
available in v1 and will be added in a later release.

Response

By default the response is a bare array of briefs:

[
  {
    "brief_id": "…",
    "title": "Red Sea diversions extend Asia–Europe transit",
    "summary": "## Summary\n\nCarriers continue to route around the Cape…",
    "severity": "critical",
    "categories": ["geopolitical", "operational"],
    "analyst": { "name": "Senior Market Analyst" },
    "published_at": "2026-06-01T00:00:00.000Z",
    "sources": [
      { "link": { "label": "Reuters", "url": "https://…" } }
    ]
  }
]

Pass include_metadata=true to wrap it with pagination metadata:

{
  "data": [ … ],
  "metadata": {
    "page": 1,
    "per_page": 25,
    "item_count": 137,
    "page_count": 6
  }
}

summary is Markdown.

Pagination

Pagination is page-based: pass page and limit. Add include_metadata=true to get
metadata.item_count and metadata.page_count, which tell you how far the feed
extends. Requesting a page beyond the end returns an empty array (not an error),
so you can page until the response is empty or page exceeds page_count.

Affected shipments

For any brief, list the shipments in your account that the brief affects:

curl \
    -s '{{baseUrl}}/risk-briefs/{brief_id}/shipments' \
    -H 'X-API-Key: {{apiKey}}'

Each shipment echoes the identifiers Vizion holds for the reference; any of them may
be null. Like the list endpoint, the response is a bare array by default (add
include_metadata=true for the { data, metadata } envelope):

[
  {
    "reference_id": "…",
    "container_id": "MSKU1234567",
    "booking_number": null,
    "bill_of_lading": null,
    "carrier_scac": "MAEU"
  }
]

An unknown brief_id returns an empty array.

Errors

Server-side failures follow the standard status codes.