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/v2Explorer 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
| Goal | Endpoint | Primary scope |
|---|---|---|
| Find normalized incidents | GET /incidents | Depends on category |
| Search ontology entities | GET /entities | intel:explorer |
| Read a single entity | GET /entities/{entityId} | intel:explorer |
| Traverse relationships | GET /entities/{entityId}/graph | intel:explorer |
| Read workspace company financial history | GET /entities/{entityId}/financial-observations | intel:finint (workspace key) |
| Fuse cyber and market exposure for a company | GET /entities/{entityId}/fusion | intel:explorer (workspace key) |
| Record and read evidenced claims | /ledger/* (Ontology Ledger) | ledger:read, ledger:write |
| Read prediction markets | GET /markets | intel:finint |
| Read financial indicators | GET /finint | intel:finint |
| Screen SEC filings, insider trades, and federal awards | GET /disclosures | intel:disclosures |
| Find extracted decision signals | GET /signals | Depends on domain |
| Traverse a cyber-focused graph | GET /cyber/graph | intel:cyber |
| Search CVEs | GET /cyber/cves | intel:cyber |
| Read a CVE disclosure or retained revision | GET /cyber/cves/{cveId} | intel:cyber |
| Search threat actors | GET /cyber/actors | intel:cyber |
| Look up a domain's DNS footprint | POST /cyber/dns/lookups | intel:cyber (Pro and Elite, workspace key) |
| Read a domain's DNS snapshot history | GET /cyber/dns/snapshots | intel: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:
| Field | Meaning |
|---|---|
occurredAt | When the incident happened or is forecast to happen |
firstObservedAt | When Y2 first observed the incident |
lastObservedAt | When 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"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"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"| Field | Meaning |
|---|---|
counterparties | Suppliers, customers, parents, subsidiaries, and operated systems, from catalog ties or evidenced ledger claims (provenance) |
timeline | Dated events, newest first, each with domain, path, provenance, and a public source ID |
undated | Events without a source time, kept visible instead of placed at a guessed date |
adjacencies | A market event that followed a cyber event within adjacencyDays. Timing, not causation |
topics | Workspace topics whose subject sits on the exposure path |
coverage | Read 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:
kind | Source | What one row is |
|---|---|---|
material_event | SEC Form 8-K and 8-K/A | One current report, classified by its most material item |
insider_transaction | SEC Forms 3, 4, and 5 and amendments | One Section 16 filing with up to 25 transaction lines |
ownership_stake | SEC Schedule 13D and 13D/A | One beneficial-ownership filing with its reporting persons |
federal_award | USAspending.gov | One 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_ofthe issuer. - A contract recipient
suppliesthe awarding office. A grant's awarding officesuppliesthe recipient. An office ispart_ofits 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
| Scope | Accepted operations |
|---|---|
intel:explorer | Entities, entity details and graphs, cyber-market fusion, unfiltered incidents, and general signals |
intel:finint | Markets, FININT indicators, company financial history, non-cyber categorized incidents, and markets or supply-chain signals |
intel:cyber | Cyber graph, CVE lists and disclosures, actor lists, cyber incidents, cyber or technology signals, and DNS footprints (Pro and Elite) |
intel:disclosures | SEC 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 need | Use OSINT v1 when you need |
|---|---|
| Stable entity and incident identity | Broader normalized event feeds |
| Relationships and graph traversal | Source-health and source-specific surfaces |
| Bounded related-resource expansion | Country, regional, and geospatial feeds |
| Semantic FININT and decision signals | NDJSON or GeoJSON representations where documented |