Y2 Elite workspaces are rolling out for teams
Y2Y2Docs

Query the Intel API (v2)

Find ontology incidents, entities, signals, markets, financial indicators, disclosures, and cyber graphs

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

Explorer investigation boards are an in-app feature. The public Intel API exposes the ontology resources that can inform an investigation, but it does not expose investigation-board CRUD endpoints.

Choose a collection

GoalEndpointPrimary scope
Find normalized incidentsGET /incidentsDepends on category
Search ontology entitiesGET /entitiesintel:explorer
Read a single entityGET /entities/{entityId}intel:explorer
Traverse relationshipsGET /entities/{entityId}/graphintel:explorer
Read workspace company financial historyGET /entities/{entityId}/financial-observationsintel:finint (workspace key)
Fuse cyber and market exposure for a companyGET /entities/{entityId}/fusionintel:explorer (workspace key)
Record and read evidenced claims/ledger/* (Ontology Ledger)ledger:read, ledger:write
Read prediction marketsGET /marketsintel:finint
Read financial indicatorsGET /finintintel:finint
Screen SEC filings, insider trades, and federal awardsGET /disclosuresintel:disclosures
Find extracted decision signalsGET /signalsDepends on domain
Traverse a cyber-focused graphGET /cyber/graphintel:cyber
Search CVEsGET /cyber/cvesintel:cyber
Read a CVE disclosure or retained revisionGET /cyber/cves/{cveId}intel:cyber
Search threat actorsGET /cyber/actorsintel:cyber
Look up a domain's DNS footprintPOST /cyber/dns/lookupsintel:cyber (Pro and Elite, workspace key)
Read a domain's DNS snapshot historyGET /cyber/dns/snapshotsintel:cyber (Pro and Elite, workspace key)

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:

FieldMeaning
occurredAtWhen the incident happened or is forecast to happen
firstObservedAtWhen Y2 first observed the incident
lastObservedAtWhen Y2 most recently observed or refreshed the incident

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"

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"

Supported includes are observations, markets, entities, primaryPlace, and relatedIncidents.

curl --get \
  "https://api.y2.dev/api/v2/entities/ent_0123456789abcdef01234567" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "include=relations,relatedEntities,incidents" \
  --data-urlencode "fields[entities]=kind,name,aliases,updatedAt"

Supported includes are relations, relatedEntities, incidents, markets, observations, companyIdentity, and financialObservations. The last two apply to organization and vendor entities. Financial observations are scoped to the key's workspace.

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"
FieldMeaning
counterpartiesSuppliers, customers, parents, subsidiaries, and operated systems, from catalog ties or evidenced ledger claims (provenance)
timelineDated events, newest first, each with domain, path, provenance, and a public source ID
undatedEvents without a source time, kept visible instead of placed at a guessed date
adjacenciesA market event that followed a cyber event within adjacencyDays. Timing, not causation
topicsWorkspace topics whose subject sits on the exposure path
coverageRead budgets that were reached and what each source does not cover

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

Screen disclosures

GET /disclosures lists primary-source records that companies and the federal government publish:

kindSourceWhat one row is
material_eventSEC Form 8-K and 8-K/AOne current report, classified by its most material item
insider_transactionSEC Forms 3, 4, and 5 and amendmentsOne Section 16 filing with up to 25 transaction lines
ownership_stakeSEC Schedule 13D and 13D/AOne beneficial-ownership filing with its reporting persons
federal_awardUSAspending.govOne contract action of $5M or more, or grant action of $10M or more

Y2 reads SEC EDGAR twice a day and USAspending once a day. Each row links to its primary record in source.url: the SEC filing index or the USAspending award page.

Filter with kind, category, severity, entityId, q, minAmountUsd, and sinceMs. sort=amount orders insider values or award obligations largest first and requires kind.

curl "https://api.y2.dev/api/v2/disclosures?kind=insider_transaction&category=buy&sort=amount&limit=10" \
  -H "Authorization: Bearer $Y2_API_KEY"

Every party is an ontology entity. Y2 matches an issuer, insider, or filer by SEC CIK and a recipient by SAM Unique Entity ID first. A new name is compared with existing entities by governed entity resolution before Y2 creates an entity, so a company that files with the SEC and receives federal contracts is one entity. A party that cannot be linked without risking a false merge has entity: null.

Disclosures also add relationships to the graph:

  • An officer or director is part_of the issuer.
  • A contract recipient supplies the awarding office. A grant's awarding office supplies the recipient. An office is part_of its department.

Each relationship records when it was first and last evidenced and cites the disclosure's observation in provenance.observation. Use entityId to list every disclosure that names a company, insider, or agency.

occurredAt is the event, transaction, or action date. publishedAt is the SEC filing date or the award action date. Both are provider calendar dates at midnight UTC.

Read CVE disclosures

GET /cyber/cves keeps the entity list contract: stable ent_... identifiers, data, meta, links, cursor pagination, and q search. Each row adds a compact disclosure summary and links to its detail, public page, and share card. Use fields[entities] to select the fields your integration needs.

The cve summary includes source status, primary CVSS, KEV membership, EPSS, remediation status, and affected-product/reference counts. summaryAvailable: false means the compact summary has not been projected yet; full detail may still be available. Existing catalog attributes remain present during collection updates.

curl --get "https://api.y2.dev/api/v2/cyber/cves" \
  --header "Authorization: Bearer $Y2_API_KEY" \
  --data-urlencode "q=CVE-2021-27460" \
  --data-urlencode "limit=10"

curl "https://api.y2.dev/api/v2/cyber/cves/CVE-2021-27460" \
  --header "Authorization: Bearer $Y2_API_KEY"

The detail contains source-specific CVSS metrics, affected products and version ranges, remediation, references, weaknesses, KEV, EPSS, SSVC, exploit references, and source retrieval times when collected. It reads the same normalized public disclosure as the Cyber UI and public page. Private workspace notes and investigations are excluded.

The detail returns data.type: "cve_disclosure" and the same data.id as the ontology entity. Its numeric dates use Unix milliseconds, matching public JSON. Summary dates and RecordSource.retrievedAt use RFC 3339 as in other v2 lists.

Pass revision=<64-character SHA-256> to retrieve a retained historical disclosure. An unknown CVE or revision returns 404; an invalid identifier or revision returns 400. Rejected CVEs remain readable with their status. A missing assessment or fix means the retained sources do not report one.

Both endpoints retain the intel:cyber scope and documented x402 access. Reading a CVE does not trigger provider collection. See CVE disclosures for collection coverage, source authority, and ontology behavior.

Look up DNS footprints

POST /cyber/dns/lookups returns the DNS footprint of a domain from DNSDumpster. The footprint contains A, MX, NS, CNAME, and TXT records. Each address includes its network operator (ASN), netblock, country, reverse DNS, and HTTP and TLS banners. Send domain. Or send entityId to use the official website that Y2 records for that entity.

curl -X POST "https://api.y2.dev/api/v2/cyber/dns/lookups" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

A snapshot younger than 14 days answers every caller with outcome: "reused". A reused snapshot does not use the workspace allowance. Otherwise Y2 takes a new snapshot with outcome: "fetched". A new snapshot uses one monthly DNS lookup. Pro includes 5. Elite includes 1,000. usage reports the allowance after the request.

A failed provider call returns the lookup to the allowance. The response is 429 or 503. Retry after the Retry-After value.

Each snapshot keeps receivedAt, the time when the answer arrived. truncated is true when the provider has more than the 50 A records that it returned. GET /cyber/dns/snapshots?domain= lists stored snapshots, newest first. It never uses the allowance.

Snapshots add the domain, hosts, addresses, netblocks, and network operators to the graph. ontology.linkedEntities lists known organizations whose official website is the domain. See DNS footprints in the graph for each entity and relationship.

Lookups need a workspace-bound key. They are not available through x402. With the local MCP server, call createDnsLookupV2 or listDnsSnapshotsV2 through y2_call_api.

Select the correct scope

ScopeAccepted operations
intel:explorerEntities, entity details and graphs, cyber-market fusion, unfiltered incidents, and general signals
intel:finintMarkets, FININT indicators, company financial history, non-cyber categorized incidents, and markets or supply-chain signals
intel:cyberCyber graph, CVE lists and disclosures, actor lists, cyber incidents, cyber or technology signals, and DNS footprints (Pro and Elite)
intel:disclosuresSEC 8-K, Form 3/4/5, and Schedule 13D filings and federal contract and grant awards (Pro and Elite)

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 key or their documented x402 payment flow. Company financial history and fusion require a workspace-bound key because they read workspace research. 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?

Use Intel v2 when you needUse OSINT v1 when you need
Stable entity and incident identityBroader normalized event feeds
Relationships and graph traversalSource-health and source-specific surfaces
Bounded related-resource expansionCountry, regional, and geospatial feeds
Semantic FININT and decision signalsNDJSON or GeoJSON representations where documented

Endpoint reference