Query the Intel API (v2)

Intel v2 turns normalized observations into stable incidents, entities, relationships, markets, and decision signals. Use it when your integration needs to follow identity and relationships instead of processing a raw event feed.

The base URL is:

https://api.y2.dev/api/v2

Choose a collection

GET /api/v2/changes is the durable change feed for public intelligence resources. It uses osint:read, not an Intel scope; see Integration Recipes for a checkpointed ingestion pattern.

List incidents

Start with the narrowest category, lifecycle, severity, and time filters your application can use. sinceMs is a lower bound on lastObservedAt, expressed in Unix milliseconds.

Incident timestamps answer different questions:

A forecast incident can have an occurredAt value years in the future while both observation timestamps reflect when Y2 received the supporting information. Use lastObservedAt, not occurredAt, as an incremental polling watermark.

curl --get "https://api.y2.dev/api/v2/incidents" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "category=cyber" \
  --data-urlencode "severity=high" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=50" \
  --data-urlencode "fields[incidents]=title,severity,status,lastObservedAt"

List collections return data, meta, and links. Follow links.next until it is null; the cursor is opaque and bound to the request's filters. Limits are clamped to 1–500.

For incremental polling, convert the largest returned lastObservedAt value to Unix milliseconds and pass it on the next request:

curl --get "https://api.y2.dev/api/v2/incidents" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "sinceMs=1786374126243" \
  --data-urlencode "fields[incidents]=title,status,occurredAt,firstObservedAt,lastObservedAt"

Drill into related context

An incident or entity detail request returns its primary resource by default. Use include to request only the bounded related collections you need.

curl --get \
  "https://api.y2.dev/api/v2/incidents/inc_0123456789abcdef01234567" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "include=observations,entities,primaryPlace" \
  --data-urlencode "fields[incidents]=title,severity,status,lastObservedAt" \
  --data-urlencode "fields[observations]=title,severity,observedAt,geometry"

Sparse fieldsets use fields[incidents], fields[entities], fields[markets], fields[observations], fields[finint], or fields[signals] as appropriate. The server always retains resource identity fields and rejects unsupported fields or includes. A request can contain at most 24 values in each projection parameter.

Traverse a graph

Use the general entity graph after resolving an ent_... ID from /entities. Its breadth-first traversal accepts depth=0–3, supports a comma-separated relationKinds filter, and is capped at 200 nodes.

curl --get \
  "https://api.y2.dev/api/v2/entities/ent_0123456789abcdef01234567/graph" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "depth=2" \
  --data-urlencode "relationKinds=affects,targets,uses"

For a CVE, threat actor, or malware family, /cyber/graph offers a cyber-specific traversal. Pass at least one of rootCveId, rootActorId, or rootMalwareFamilyId; its depth is limited to 1–2.

Follow a company across cyber and market events

Company endpoints read workspace research, so they require a workspace-bound API key and never accept x402 payment.

GET /entities/{entityId}/financial-observations pages through the workspace's recorded financial facts for an organization or vendor, newest recorded first. Filter with metricKey (an index) or factType (applied per page, so an empty page can still carry a next cursor). Each fact keeps its reporting period, recorded time, source provenance, and, for SEC imports, the retained JSON record pointer. History reflects what Y2 retained, not complete filing coverage.

GET /entities/{entityId}/fusion places cyber, market, supply-chain, and geopolitical events about the company and the parties on its exposure path on one timeline:

curl --get \
  "https://api.y2.dev/api/v2/entities/ent_0123456789abcdef01234567/fusion" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "windowDays=90" \
  --data-urlencode "adjacencyDays=7"

See Cyber-market fusion for what the view claims and what it does not.

Select the correct scope

When /signals has no domain filter, any Intel scope is accepted. Other signal domains require intel:explorer. Authenticated requests can receive authorized private and workspace rows; x402 callers receive global and community rows only.

New API keys with Intel scopes require Pro or Elite. Existing Lite API keys remain valid under the current grace policy, while Lite retains its in-app Intel surfaces. See Plans and Limits for the complete product-entitlement matrix.

Authenticate or pay per request

Intel endpoints accept a scoped bearer API key or their documented x402 payment flow, except company financial history and fusion, which read workspace research and require a workspace-bound key. A request without Authorization begins with 402 Payment Required; retry it with the signed payment header described by that endpoint. Do not send both a bearer key and x402 payment for the same request.

Intel v2 or OSINT v1?

Endpoint reference