API Overview
Choose the correct Y2 API surface, authentication path, version root, and generated contract
Y2 exposes a versioned HTTP API for reports, profile orchestration, Projects, Automations, news, Situation Room data, ontology-backed intelligence, Y2 Global Knowledge retrieval, webhook configuration, subscription delivery, Agent Y2 streams, and x402 receipts.
Use the generated reference for exact contracts
This overview helps you choose a surface. The generated Endpoint Reference defines the exact path, operation-level server, parameters, body, scopes, authentication modes, media types, schemas, and response headers.
Request path
Base URLs
| Surface | Base URL | Contains |
|---|---|---|
| Core v1 | https://api.y2.dev/api/v1 | Agent Y2, reports, profiles, Projects, Automations, news, OSINT, webhooks, subscriptions, receipts |
| Intelligence v2 | https://api.y2.dev/api/v2 | Change feed, incidents, entities, graphs, markets, FININT, signals, cyber |
The OpenAPI document defines core operation paths relative to /api/v1. Its v2 operation paths
already contain /api/v2 and override the server to https://api.y2.dev. A generator that honors
operation-level servers produces the correct URL; do not concatenate a v2 path onto the v1 base.
Choose authentication
| Path | Use when | Identity and limits |
|---|---|---|
| Bearer API key | The integration should access a Y2 workspace repeatedly | Key scopes, key IP restriction, per-key quota, and workspace/user aggregate quota |
| x402 | A listed read operation should be paid per request without provisioning a key | Payment signature, replay protection, wallet quota, endpoint ceiling, and settlement |
| Public receipt lookup | A client needs the status of an x402 settlement nonce | No API key; receipt lookup only |
New keys require Pro or Elite. Lite cannot create keys, though keys already covered by the Lite grace policy continue at 10 requests per minute and 500 per day. x402 support is independent and is declared one operation at a time.
See Authentication for workspace binding and scopes, or x402 Payments for the payment handshake.
Choose a surface
Agent Y2
Stream the preconfigured workspace-aware agent through native or OpenAI-compatible SSE
Reports
List and retrieve generated reports, text, signals, graphs, audio, and audio text
Profiles
List subscription records and create, replace, patch, or delete owned profiles
Projects
Create and manage owner-private intelligence workspaces
Automations
Manage durable Agent Y2 definitions, manual runs, and run history
News
Read direct-source news items, AI recaps, and the current feed catalog
OSINT
Read v1 Situation Room events, map data, country resources, transport, markets, and source health
Intel v2
Consume ontology-backed changes, incidents, entities, graphs, FININT, signals, and cyber data
Y2 Global Knowledge
Retrieve bounded, authorized evidence across Y2 reports and signal assessments
Webhooks
Create, inspect, update, test, and delete webhook configurations
Subscriptions
Change the supported delivery configuration for a profile subscription
Payments
Look up an x402 receipt by nonce
Core v1 route map
| Area | Routes | Bearer scope | x402 |
|---|---|---|---|
| Agent Y2 | POST /agent-y2/chat/stream, POST /chat/completions | agent:y2 | No |
| Reports | GET /reports, GET /reports/{reportId} and report subresources | reports:read; audio uses reports:audio | Yes where declared |
| Profiles | GET, POST /profiles; PUT, PATCH, DELETE /profiles/{profileId} | Read or write scope by operation | No |
| Projects | GET, POST /projects; GET, PATCH /projects/{projectId} | projects:read or projects:write | No |
| Automations | GET, POST /automations; GET, PATCH /automations/{automationId}; GET, POST /automations/{automationId}/runs | automations:read or automations:write | No |
| News | GET /news, /news/recaps, /news/feeds | news:read | Yes |
| OSINT | GET /osint/* including country resources | osint:read | Yes |
| Webhooks | /webhooks, /webhooks/{webhookId}, /test | webhooks:manage | No |
| Subscription delivery | PATCH /subscriptions/{subscriptionId}/delivery | webhooks:manage | No |
| x402 receipt | GET /x402/receipts/{nonce} | None | Public lookup |
The reports list is workspace-contextual for bearer callers. In particular,
GET /profiles lists profile subscription records available to the key workspace; it is not a
public community-catalog search endpoint.
Intel v2 route map
| Route | Bearer scope |
|---|---|
GET /changes | osint:read |
GET /incidents, GET /incidents/{incidentId} | Any of intel:explorer, intel:finint, or intel:cyber |
GET /entities, /entities/{entityId}, /entities/{entityId}/graph | intel:explorer |
GET /markets, /finint | intel:finint |
GET /signals | Any of intel:explorer, intel:finint, or intel:cyber |
GET /cyber/graph, /cyber/cves, /cyber/actors | intel:cyber |
POST /intel/knowledge/retrieve | intel:knowledge |
These paths are relative to https://api.y2.dev/api/v2 in the table above. Every current v2
operation except Y2 Global Knowledge also declares x402 metadata in OpenAPI. Global Knowledge is
API-key-only because its authorization requires a Y2 workspace principal.
Success representations
Do not assume every successful endpoint returns the same JSON envelope.
| Contract kind | Typical response |
|---|---|
| Collection | { "data": [...], "meta": {...}, "links": {...} } or operation-specific pagination fields |
| Resource | { "data": {...} } plus operation-specific fields and headers |
| Representation | Plain text, audio metadata, or an optional redirect as documented |
| Agent stream | text/event-stream in AI SDK UI or OpenAI-compatible chunk format |
| Delete | 204 No Content for the documented destructive operations |
Collection cursors are opaque. Persist the returned next cursor or watermark and send it back unchanged; do not parse it or construct one from record IDs.
Errors
JSON failures use application/problem+json with stable top-level fields and an actionable
resolution hint:
{
"type": "https://api.y2.dev/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid API key",
"instance": "urn:y2:request:req_...",
"code": "INVALID_API_KEY",
"requestId": "req_...",
"resolution": "Send a valid Y2 API key in the Authorization: Bearer header."
}| Status | Common meaning |
|---|---|
400 | Invalid query, ID, cursor, JSON, or request body |
401 | Missing or invalid bearer authentication |
402 | x402 challenge or rejection; on Agent Y2, plan or credit exhaustion instead |
403 | Missing scope, ineligible plan, IP restriction, or tenant authorization failure |
404 | Resource or thread not found in the allowed scope |
409 | Idempotency or resource-state conflict |
412 | If-Match does not match the current representation |
415 / 422 | Unsupported representation or operation-specific semantic failure |
429 | Key, account, endpoint, wallet, or abuse-control limit exceeded |
500 / 503 | Internal failure, unavailable dependency, or unavailable data path |
Retain X-Request-Id and the problem code in integration logs. Follow Retry-After only when the
response indicates a retryable limit or availability failure.
Version and diagnostic headers
| Header | Meaning |
|---|---|
X-Y2-API-Version | 1.0 for v1 operations and 2.0 for v2 operations |
X-Y2-Schema-Version | Shared response-schema version, currently 1.2 |
X-Request-Id | Per-request diagnostic identifier |
ETag | Strong validator on operations that support conditional writes |
Location | Canonical URL after resource creation |
Idempotency-Key | Echoed retry key on operations that support idempotent creation |
X-Y2-Next-Cursor, X-Y2-As-Of, X-Y2-Watermark | Collection and change-feed checkpoints where applicable |
Explore and verify
Read the task guide
Start with Integration Recipes or the manual guide for the product area.
Open the generated operation
Verify method, server, scope, x402 metadata, parameters, request body, and responses.
Run a bounded request
Use API Workbench or curl with the smallest useful limit.
Capture the contract evidence
Check the body and diagnostic headers before implementing pagination, retries, or mutations.