---
title: "Use the OpenAPI Contract"
description: "Download the API specification and generate a client"
canonical: https://y2.dev/docs/api/openapi/
---

# Use the OpenAPI Contract

Download the API specification and generate a client

Use Y2's OpenAPI 3.1 document to inspect operations or generate a client. The [endpoint reference](https://y2.dev/docs/api/reference) uses the same document.

## Get the specification

| Format | URL                               |
| ------ | --------------------------------- |
| YAML   | `https://y2.dev/api/openapi.yaml` |
| JSON   | `https://y2.dev/openapi.json`     |

[Download the YAML specification](https://y2.dev/api/openapi.yaml).

## Compose the correct request URL

| Operation path      | Server                      | Complete URL                          |
| ------------------- | --------------------------- | ------------------------------------- |
| `/reports`          | `https://api.y2.dev/api/v1` | `https://api.y2.dev/api/v1/reports`   |
| `/api/v2/incidents` | `https://api.y2.dev`        | `https://api.y2.dev/api/v2/incidents` |

Use an operation-level or path-level `servers` value before the document-level value. Do not add `/api/v1` to a path that starts with `/api/v2`.

## Import into an API client

### Import the specification

Import `https://y2.dev/api/openapi.yaml` into a client that supports OpenAPI 3.1. Check the selected operation's server.

### Add a credential

[Create a scoped key](https://y2.dev/docs/api/authentication#create-a-key). Store it in the client's secret or environment settings. Set the authorization header to `Bearer {{Y2_API_KEY}}`. Keep the key out of exported collections.

### Run a read request

Start with a GET operation and a small `limit`. Check the status, body, and [response headers](https://y2.dev/docs/api/responses#version-and-diagnostic-headers).

## Generate TypeScript types

```
npx openapi-typescript https://y2.dev/api/openapi.yaml \
  --immutable \
  --alphabetize \
  --output src/y2-api.d.ts
```

The command creates `src/y2-api.d.ts`. See [Build a TypeScript Client](https://y2.dev/docs/sdks/typescript) for a complete request.

For other clients, choose an OpenAPI 3.1 generator that supports operation-level servers. Check its handling of errors, streaming, NDJSON, GeoJSON, and x402. SSE and payment flows can require additional transport code.

## Y2 extensions

Prop

Type

The `security` array defines authentication alternatives. Agent Y2 accepts bearer keys only. Operations with an empty security alternative and `x-x402` start payment without `Authorization`. Receipt lookup is public.

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

[Client guides](https://y2.dev/docs/sdks)

[x402 payments](https://y2.dev/docs/api/x402)
