Client Libraries and Tools
Choose a typed client, direct HTTP integration, or command-line workflow for the Y2 API
Y2 publishes an OpenAPI 3.1 contract that can drive types, generated clients, request tools, and tests. Treat that contract—not a package's convenience method names—as the compatibility boundary.
API-key access
New API-key access requires Pro or Elite. Existing grandfathered Lite integrations retain their existing keys during the grace period. Create a key in the active workspace and grant only the scopes the client needs.
Choose an integration style
TypeScript client
Generate path and schema types, then call Y2 with a small typed fetch wrapper.
Python client
Build a synchronous or asynchronous HTTP client around the published response contract.
Command line
Install Y2 Information Dominance for agent workflows, or use curl and jq for direct API work.
API Workbench
Explore path and query parameters, run live reads, and copy starter snippets.
| Option | Best for | Contract fidelity | Main responsibility |
|---|---|---|---|
| Y2 Information Dominance | Interactive agent work and one-off prompts | Uses Agent Y2 or a configured OpenAI-compatible endpoint | Keep the harness and credentials current |
| Generated OpenAPI client | Broad API coverage | Regenerate when the spec changes | Review generator behavior |
| Generated types + native HTTP | Controlled production integrations | Types come directly from OpenAPI | Maintain a small transport layer |
| curl or Workbench | Exploration and operations | Request is visible and explicit | Handle parsing and pagination |
| Separately released package | Convenience APIs | Depends on its release date | Verify version and operation coverage |
Verify package-specific APIs
Package installation names, exported classes, and helper methods are release-specific and are not defined by the platform OpenAPI file. Before adopting a separately released client, compare its generated operation IDs and models with the current endpoint reference.
Start from the contract
Download the production description:
curl --fail --silent --show-error \
"https://y2.dev/api/openapi.yaml" \
--output openapi.yamlThen validate the assumptions that most often break generated clients:
- v1 paths inherit
https://api.y2.dev/api/v1; - Intel v2 operations override the server with
https://api.y2.dev; - bearer scopes are declared in
x-required-scopes; - supported reads can declare x402 as a second security mode;
- errors use
application/problem+jsonwith stable top-levelcodeandrequestId; - list pagination uses
links.nextandmeta.page.nextCursorwhere applicable; and - some endpoints can return NDJSON, GeoJSON, Markdown, plain text, audio redirects, or SSE.
Use a minimal bearer request
Every bearer client needs the same basic transport behavior:
export Y2_API_KEY="y2_..."
curl --fail-with-body \
"https://api.y2.dev/api/v1/news?topics=markets&limit=5" \
--header "Authorization: Bearer $Y2_API_KEY" \
--header "Accept: application/json"Keep the API key on a server, worker, job runner, or local development machine. Do not ship it in a browser bundle or mobile application.
Model the common response shapes
Do not assume every successful response is { data: [...] }. A generated client must preserve
declared media types and status codes, especially 204 deletes, 302 audio redirects,
text/event-stream, application/x-ndjson, application/geo+json, and text/markdown.
Regenerate safely
Pin the input
Generate from a reviewed copy of https://y2.dev/api/openapi.yaml or pin the generated output
in source control. Avoid silently regenerating from a moving URL during every production build.
Review operation IDs and servers
Stable operation IDs become method names in many generators. Confirm that v2 paths do not receive the v1 prefix.
Add transport policies
Configure timeouts, bounded retries, rate-limit handling, idempotency keys for supported writes, and secret management outside generated files.
Smoke-test one operation per representation
Test ordinary JSON, pagination, a mutation, and any special representation your integration consumes. Generated types alone do not prove deployed runtime behavior.
Coverage checklist
Use the generated reference to verify the exact operation rather than inferring coverage from a client namespace.
| Surface | Special handling to verify |
|---|---|
| Profiles | Separate prf_ profile and sub_ subscription resources; PUT versus PATCH |
| Reports | Compact defaults, bounded includes, Markdown/text/audio representations |
| News | Topic catalog, JSON or NDJSON pagination, cache-readiness errors |
| OSINT | JSON, NDJSON, and GeoJSON; source availability varies |
| Intel v2 | Operation-level server override and ontology IDs |
| Webhooks | Idempotency, ETags, write-only secrets, and 204 deletion |
| Agent Y2 | API-key-only SSE transport, not an ordinary JSON response |
| x402 | Payment challenge and settlement headers outside normal bearer auth |