Use the OpenAPI Contract

Download, inspect, generate from, and safely update Y2's OpenAPI 3.1 specification

Y2 publishes one OpenAPI 3.1 document as the machine-readable contract for its REST API. The generated endpoint reference, API Workbench, repository TypeScript declarations, and contract tests all consume that source.

One source of truth

Use the generated Endpoint Reference for operation details. Use this page to locate, consume, or update the raw specification. Do not manually edit files under content/docs/api/reference or src/lib/openapi-reference-nav.generated.ts.

Get the specification

The production URL is:

https://y2.dev/api/openapi.yaml

The app serves the same repository file at /api/openapi.yaml in development and production.

Agents and function-calling clients can use the equivalent JSON representation at:

https://y2.dev/openapi.json

Download the OpenAPI specification

Compose the correct request URL

The document contains more than one server because v1 and v2 use different path shapes.

Operation shape	Server	Example result
v1 path such as `/reports`	`https://api.y2.dev/api/v1`	`https://api.y2.dev/api/v1/reports`
v2 literal path such as `/api/v2/incidents`	`https://api.y2.dev` operation override	`https://api.y2.dev/api/v2/incidents`

OpenAPI tooling should honor an operation- or path-level servers value before the document-level servers. Avoid blindly prepending /api/v1 to an Intel v2 path.

Read Y2 extensions

In addition to standard OpenAPI fields, operations can declare:

Prop

Type

The standard security array remains authoritative for allowed authentication alternatives. Agent Y2 operations are bearer-key only. Operations with an empty security alternative and x-x402 begin the payment flow without Authorization. The sanitized x402 receipt lookup is public.

Import into an API client

Import the production URL

Import https://y2.dev/api/openapi.yaml into a client that supports OpenAPI 3.1.

Configure the server

Confirm that the selected operation uses the intended v1 or v2 server. Some clients expose the document's server list as an environment selector.

Add a scoped credential

Store Y2_API_KEY in the client's secret or environment facility and configure bearer auth as Bearer {{Y2_API_KEY}}. Never commit an exported collection containing the key.

Validate a read

Start with a bounded GET whose required scope is on the key. Check X-Request-Id, API version, schema version, and rate-limit headers as well as the body.

Generate types or a client

For a TypeScript project, generate path and component types directly:

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

For a full client, use an OpenAPI 3.1-compatible generator and review its handling of operation-level servers, streaming responses, application/problem+json, NDJSON, GeoJSON, and x402 extensions. Generated code is a starting point; SSE and payment flows commonly need explicit transport code.

TypeScript guide

Python guide

CLI guide

API Workbench

Update the contract in this repository

The editable source is public/api/openapi.yaml.

Change the source specification

Update the operation, schema, response, examples, scopes, and x402 metadata together. Keep operation IDs stable unless the operation itself is intentionally replaced.

Regenerate derived artifacts

bun run docs:openapi
bun run generate:api-types
bun run generate:api-contract-fixtures

These commands update the Fumadocs operation pages and nav, immutable TypeScript declarations, and schema-derived response fixtures.

Run the contract gate

bun run check:api-contract
bun run docs:source

The contract gate lints the OpenAPI file, checks generated types, verifies the 54-operation manifest against Convex HTTP registrations, validates response fixtures against schemas, and runs focused tests for IDs, pagination, representations, projections, middleware, and webhook identity.

Review generated scope

Confirm that generated changes correspond to the intended source edit. Never patch a generated endpoint page to conceal a mismatch in public/api/openapi.yaml.

Synthetic fixtures are not live API captures

generate:api-contract-fixtures derives representative bodies from the schemas. The contract tests prove schema consistency and prevent persistence-field leakage; they do not prove that a deployed environment currently returns those exact values.

Repository artifacts

public/api/openapi.yaml

content/docs/api/reference/

src/lib/openapi-reference-nav.generated.ts

src/lib/api-contract.generated.d.ts

convex/api/contract/manifest.ts

convex/api/contract/fixtures/responses.json