AI Quickstart
Ground an AI coding agent in Y2's generated docs, API contract, tenant model, and verification loop
Use this page before asking a coding agent to build against Y2. It gives the agent stable discovery URLs, separates the v1 and v2 API roots, identifies the required scopes, and keeps credentials out of the prompt.
Paste this into Claude Code, Codex, Pi, Hermes, OpenClaw, or OpenCode before integrating the Y2 API.
The button copies a short bootstrap prompt that tells the agent to read this page and the MCP guide. It intentionally links to current documentation instead of embedding a second copy of plan limits that can drift.
Agent build loop
Discover the documentation
Start with https://y2.dev/llms.txt. It is the compact index generated from the documentation
tree. Load llms-full.txt only when the task needs broad cross-product context.
Read the relevant guide and operation
Use the manual guide for intent and workflow, then use the generated endpoint reference or raw OpenAPI operation for the exact path, method, parameters, scopes, schemas, x402 setting, and response headers.
Resolve authentication and tenancy
Create the API key in the workspace that should own the request. Grant only the documented scopes. Let Y2 derive user and workspace authorization from the key; never treat a caller- supplied user or workspace ID as proof of access.
Implement from the contract
Keep Y2_API_KEY in a server or local agent environment. Generate types from OpenAPI when
useful, but preserve Y2 response headers and structured errors in the integration layer.
Verify one real request
Run a bounded curl request or use the API Workbench. Confirm the status, response shape,
X-Request-Id, API version, pagination, and rate-limit headers before expanding the workflow.
Canonical context URLs
| Resource | URL | Use |
|---|---|---|
| Documentation index | https://y2.dev/llms.txt | Discover pages without loading the full corpus |
| Full documentation | https://y2.dev/llms-full.txt | Broad context for cross-cutting work |
| Individual raw page | https://y2.dev/docs/{path}.mdx | Load one page as Markdown |
| API guide | https://y2.dev/docs/api | Understand surfaces, auth choices, and workflow boundaries |
| Generated reference | https://y2.dev/docs/api/reference | Inspect operation-specific schemas and examples |
| OpenAPI 3.1 document | https://y2.dev/api/openapi.yaml | Generate clients and validate exact contracts |
| Authentication guide | https://y2.dev/docs/api/authentication | Choose key scopes and understand tenant resolution |
| Agent Y2 guide | https://y2.dev/docs/api/agent-y2 | Integrate native or OpenAI-compatible agent streams |
| MCP guide | https://y2.dev/docs/api/mcp | Configure the separately distributed local MCP server |
llms.txt, llms-full.txt, and raw .mdx pages are generated from content/docs during the site
build and served by the local Vite documentation middleware during development.
OpenAPI owns the wire contract
Manual guides explain goals and safe usage. If a hand-written example conflicts with a generated
operation, use public/api/openapi.yaml and the generated endpoint page as the field-level source
of truth, then report the stale guide.
Base URLs
| Surface | Base URL | Examples |
|---|---|---|
| Core v1 | https://api.y2.dev/api/v1 | Reports, profiles, news, OSINT, webhooks, subscriptions, Agent Y2 |
| Intelligence v2 | https://api.y2.dev/api/v2 | Changes, incidents, entities, graphs, markets, FININT, signals, cyber |
The OpenAPI document declares an operation-level https://api.y2.dev server for v2 paths because
those paths already include /api/v2. Do not combine the v1 base with a v2 operation path.
API-key plan and scope map
This table describes the new API-key path. An endpoint that explicitly supports x402 can also be called without an API key by completing that endpoint's payment flow.
| Surface | New key minimum | Required scope |
|---|---|---|
| Reports | Pro | reports:read |
| Report audio | Pro | reports:audio |
| Profiles | Pro | profiles:read or profiles:write by operation |
| News | Pro | news:read |
| OSINT v1 | Pro | osint:read |
| FININT and markets v2 | Pro | intel:finint |
| Cyber v2 | Pro | intel:cyber |
| Explorer entities, incidents, and graphs | Pro | intel:explorer |
| Webhook management API | Pro | webhooks:manage |
| Agent Y2 stream | Pro | agent:y2 |
| MCP docs and OpenAPI resources | None | None |
| MCP data or Agent Y2 tools | Pro for a new key | Scope used by each underlying API operation |
Lite includes in-app FININT, Cyber, Explorer, full Situation Room access, and webhook delivery, but cannot create new API keys. A Lite workspace with existing keys retains those credentials and their historical limit of 10 requests per minute and 500 per day. This grace does not grant new scopes or new key creation.
| Plan | New keys | Default per-key request limits |
|---|---|---|
| Free | 0 | No key access |
| Lite | 0 | Existing keys only: 10/minute and 500/day |
| Pro | 10 | 30/minute and 5,000/day |
| Elite | 100 | 300/minute and 50,000/day |
Elite workspaces include five seats, with larger organizations available by arrangement. Workspace members share tenant resources and account-level rate-limit aggregates; creating more keys does not multiply the workspace aggregate quota.
Give an agent safe instructions
Use this compact task template after the bootstrap prompt has loaded the docs:
Implement [specific Y2 workflow] in this codebase.
Before editing:
1. Read the relevant Y2 manual guide.
2. Read the exact operation in https://y2.dev/api/openapi.yaml.
3. Confirm the base URL, required scope, pagination, x402 support, and error responses.
Constraints:
- Read Y2_API_KEY from the server or MCP client environment only.
- Never put the key in source, browser code, prompts, tool arguments, or logs.
- Let the API key determine tenant access.
- Use the narrowest scopes and bounded page sizes.
- Handle 401, 402, 403, 404, 409/412 where documented, 429, and 5xx.
- Preserve X-Request-Id and Retry-After for diagnostics.
Verify with one bounded request and report the observed status and response shape.MCP boundary
The platform repository defines the HTTP APIs, OpenAPI contract, docs, billing rules, and Agent Y2
executor. @y2-intel/mcp is documented as a separate stdio package and its implementation is not
present in this repository.
Follow the MCP guide for the intended configuration. Before automating against a
specific package release, inspect its actual tools/list, resources/list, and prompts/list
responses instead of assuming every documented capability exists in the installed version.
When configuring a local MCP client, pass Y2_API_KEY through the client environment. Grant
agent:y2 only when the agent should be able to use entitled account actions; documentation and
OpenAPI discovery do not require that scope.
Smoke tests
Use a key that has the matching read scope. -D - prints the response headers so the agent can
verify request IDs, API version, and remaining quota instead of checking only the JSON body.