Query the OSINT API
Read normalized events, country intelligence, geospatial feeds, source health, and FININT
The OSINT API exposes source-oriented Situation Room data as canonical public resources. Use it for normalized event feeds, geospatial observations, country surfaces, provider health, prediction markets, transport and security feeds, or financial indicators.
The base URL is:
https://api.y2.dev/api/v1/osintChoose an endpoint
Events and geography
| Goal | Endpoint | Useful filters |
|---|---|---|
| List normalized threat events | GET /events | category, severity |
| Load only geolocated map events | GET /map | region |
| Compose regional and spatial filters | GET /regional | q, region, countryCode, sourceType, bbox, radius, time |
| Read report-extracted events | GET /y2-events | category, severity, countryCode |
Country intelligence
| Goal | Endpoint |
|---|---|
| Periodically generated intelligence brief | GET /countries/{countryCode}/brief |
| Primary stock index and weekly change | GET /countries/{countryCode}/markets |
| Country-linked prediction markets | GET /countries/{countryCode}/predictions |
| Recent news and report observations attributed to a country | GET /countries/{countryCode}/news |
| Country Conflict Indicators Index | GET /countries/{countryCode}/cii |
Country codes are ISO 3166-1 alpha-2 values such as US or UA.
Specialized feeds
| Family | Endpoints |
|---|---|
| Conflict and security | /cii, /cyber-threats, /military-posture, /gps-jamming |
| Transport | /aircraft, /vessels |
| Markets | /prediction-markets, /finint |
| Operations | /sources/status |
Aircraft-backed feeds are currently disabled
Aircraft ingestion has been disabled since May 8, 2026, to reserve the shared Wingbits quota
for GPS interference detection. /aircraft and /military-posture can return empty or stale
data. /gps-jamming is unaffected.
Authenticate or use x402
Every published OSINT operation accepts a bearer key with osint:read or its documented
x402 pay-per-request flow.
curl "https://api.y2.dev/api/v1/osint/events?limit=50" \
--header "Authorization: Bearer $Y2_API_KEY"A request without Authorization begins with 402 Payment Required. Retry it with the signed
payment header described in that response; do not send bearer and x402 credentials together.
Search regional events
/regional combines text, source, category, severity, region, country, time, and coordinate
filters with AND semantics. Events without coordinates remain unless you request a bounding box,
radius, or requireCoordinates=true.
curl --get "https://api.y2.dev/api/v1/osint/regional" \
--header "Authorization: Bearer $Y2_API_KEY" \
--data-urlencode "q=port disruption" \
--data-urlencode "sourceType=rss" \
--data-urlencode "category=economic" \
--data-urlencode "bbox=-10.0,35.0,40.0,65.0" \
--data-urlencode "datetime=2026-07-01T00:00:00Z/2026-07-21T23:59:59Z" \
--data-urlencode "limit=100"q searches title and falls back to description substrings. bbox is exactly
west,south,east,north in WGS 84 and cannot cross the antimeridian. Radius search requires all
three of nearLat, nearLon, and radiusKm; the maximum radius is 20,000 km.
Use datetime for new integrations. It accepts an RFC 3339 instant or inclusive start/end
interval; .. creates an open boundary. The inclusive epoch-millisecond since and until
parameters are deprecated and cannot be combined with datetime.
Read country news
Use a two-letter country code to retrieve recent news and report observations:
curl "https://api.y2.dev/api/v1/osint/countries/SA/news?limit=8" \
--header "Authorization: Bearer $Y2_API_KEY"The country filter uses the observation's geographic attribution. A Saudi pipeline event can
qualify for SA; a regional Red Sea event does not qualify merely because Saudi Arabia is
mentioned or exposed to its effects. Available geographic evidence appears in
provenance.geoResolution, including the resolution method, matched text, and related or
mentioned country codes when available. These associations do not expand the country filter.
Country news includes unexpired rss, gdelt, acled, news_terminal, and y2_report
observations, excluding seismic and weather categories. Source and expiry filters apply before
the page limit, so satellite detections do not consume the news window. The default limit is
8 and the maximum is 20; follow links.next to continue.
The API returns canonical observations with stable obs_ IDs. The country card can deduplicate
articles for display, so its headline count can differ from the API's observation count. The
News API serves a separate topic-feed cache and requires news:read; this
country-news endpoint requires osint:read.
If a country-news cursor is invalid or obsolete, the API returns HTTP 400 with
VALIDATION_ERROR. Restart without the cursor and follow the new continuation links. Integrations
carrying a cursor from before the September country-news update
need to restart their collection after that rollout. A scan that exceeds its read budget returns
QUERY_TOO_BROAD; neither error is evidence that the country has no news.
See the endpoint reference for the full response contract.
Choose JSON, NDJSON, or GeoJSON
Representation support is operation-specific and listed on each generated reference page.
JSON collection responses contain data, meta, and links. Follow links.next until it is
null.
curl "https://api.y2.dev/api/v1/osint/cyber-threats?limit=100" \
--header "Authorization: Bearer $Y2_API_KEY"You can use Accept: application/x-ndjson or Accept: application/geo+json instead of format.
Do not assume that every OSINT operation supports every representation: country briefs, country
stock indices, country CII, and source status return JSON only.
Page collections safely
JSON collections expose an opaque, filter-bound cursor through meta.page.nextCursor and
links.next. Specialized representations move the cursor to X-Y2-Next-Cursor so their body can
stay representation-native. Preserve the original filters on the next request.
The maximum limit depends on the operation: for example, /map allows 500, /regional allows
200, and country prediction pages allow 10. Use the generated reference instead of assuming one
global maximum.
Check source health before declaring absence
If a feed is empty or unexpectedly stale, inspect /sources/status:
curl "https://api.y2.dev/api/v1/osint/sources/status" \
--header "Authorization: Bearer $Y2_API_KEY"| Field | Meaning |
|---|---|
state | closed normally permits fetching; open isolates a failing source; half_open is a recovery probe state |
failureCount | Consecutive failures; a successful fetch resets it to zero |
lastSuccessAt, lastSuccessAtISO | Last success in epoch milliseconds and RFC 3339; nullable before any success |
lastFailureAt, lastFailureAtISO | Most recent failure in both time formats |
lastError | Most recent provider error when available |
Live-provider circuit breakers open after five consecutive failures and permit one probe after a
five-minute cooldown. A y2_report row represents report-enrichment health rather than a polled
provider: open means the newest recorded enrichment error is later than the latest success.
A healthy source does not prove completeness, and an empty endpoint does not prove that no real-world event occurred. Preserve source attribution and corroborate high-impact conclusions.
OSINT v1 or Intel v2?
| Use OSINT v1 when you need | Use Intel v2 when you need |
|---|---|
| Source-oriented normalized observations | Stable entity and incident identity |
| Country and provider-specific surfaces | Relationship and graph traversal |
| GeoJSON or NDJSON where advertised | Sparse semantic projections and bounded relations |
| Provider health and circuit-breaker state | Intel-specific FININT, cyber, or Explorer scopes |