---
title: "AI Quickstart"
description: "Give a coding agent the Y2 contract and verify its first request"
canonical: https://y2.dev/docs/api/agentic-dx/
---

# AI Quickstart

Give a coding agent the Y2 contract and verify its first request

Use this guide to build a Y2 integration with a coding agent. Keep the API key outside the prompt.

AI Quickstart

Paste this into Claude Code, Codex, Pi, Hermes, OpenClaw, or OpenCode before integrating the Y2 API.

**Copy prompt** gives the agent links to current Y2 documentation.

## Build the integration

### Find the relevant documentation

Read `https://y2.dev/llms.txt` for the page index. Read the task guide and its generated endpoint reference. Use `llms-full.txt` only when the task needs the full documentation.

### Check the operation

Confirm the method, server, parameters, body, scopes, and response format in [OpenAPI](https://y2.dev/api/openapi.yaml). For v2 paths, use the operation's server override.

### Set authentication

[Create a key](https://y2.dev/docs/api/authentication#create-a-key) in the workspace that owns the requested resources. Grant only the required scopes. Store `Y2_API_KEY` in the server or local agent environment.

### Implement and verify

Run one request with a small `limit`. Check the status, body, `X-Request-Id`, version, and rate-limit headers. Verify pagination and error handling before you add more operations.

## Give the agent a task

Replace the bracketed text with your task:

Agent task template

```
Implement [specific Y2 workflow] in this codebase.

1. Read the relevant guide at https://y2.dev/docs/api.
2. Read the operation in https://y2.dev/api/openapi.yaml.
3. Confirm the server, scopes, pagination, authentication, and errors.

Read Y2_API_KEY from the server or MCP client environment.
Keep it out of source, browser code, prompts, tool arguments, and logs.
Let the key determine workspace access.
Use only the required scopes and bounded page sizes.
Preserve X-Request-Id and Retry-After.

Verify one request. Report its status and response shape.
```

## Check a read request

Use a key with `reports:read` for Core v1 or `intel:finint` for Intel v2. The `-D -` option prints response headers.

**Core v1**

Terminal

```
curl -sS -D - "https://api.y2.dev/api/v1/reports?limit=1" \
  -H "Authorization: Bearer $Y2_API_KEY"
```

**Intel v2**

Terminal

```
curl -sS -D - "https://api.y2.dev/api/v2/finint?limit=1" \
  -H "Authorization: Bearer $Y2_API_KEY"
```

Expect HTTP `200` and a JSON collection. An empty `data` array is valid. For other statuses, use the [error reference](https://y2.dev/docs/api/responses#errors).

## Documentation URLs

| Resource             | URL                               |
| -------------------- | --------------------------------- |
| Page index           | `https://y2.dev/llms.txt`         |
| Full documentation   | `https://y2.dev/llms-full.txt`    |
| One page as Markdown | `https://y2.dev/docs/{path}.md`   |
| OpenAPI YAML         | `https://y2.dev/api/openapi.yaml` |
| OpenAPI JSON         | `https://y2.dev/openapi.json`     |

[Authentication and scopes](https://y2.dev/docs/api/authentication)

[Endpoint reference](https://y2.dev/docs/api/reference)

[MCP setup](https://y2.dev/docs/api/mcp)
