Types and SDKs

Generate typed clients and webhook handlers from the dartpilot OpenAPI document.

dartpilot publishes a machine-readable OpenAPI document:

https://api.dartpilot.app/v1/openapi.json

It describes the public REST API and every webhook delivery, including the signed request headers. It is public, needs no API key, and allows cross-origin requests, so generators and browser-based tools can fetch it directly.

What the document contains

• Every /v1 endpoint with its request and response schemas.
• The webhooks.eventDelivery operation, with the webhook-id, webhook-timestamp and webhook-signature headers.
• One envelope component per event (WebhookEventGameStarted, WebhookEventTournamentMatchCompleted, and so on).
• A WebhookEvent union with a discriminator on type, so generated types narrow data to the right payload: Game, GameDetail, TournamentDetail, TournamentMatch, or the ping test payload.

Generate TypeScript types

openapi-typescript turns the document into a single .d.ts file with no runtime dependency:

curl -fsS https://api.dartpilot.app/v1/openapi.json -o openapi.json
npx openapi-typescript openapi.json -o dartpilot-api.d.ts

The output includes both paths and webhooks:

import type { components, webhooks } from "./dartpilot-api";

type WebhookEvent = components["schemas"]["WebhookEvent"];
type WebhookBody =
  webhooks["eventDelivery"]["post"]["requestBody"]["content"]["application/json"];

function handle(event: WebhookEvent) {
  switch (event.type) {
    case "game.completed":
      return event.data.state; // GameDetail
    case "tournament.match.started":
      return event.data.gameId; // TournamentMatch
    case "ping":
      return event.data.webhookId; // test payload
  }
}

const receive = (body: WebhookBody) => handle(body);

Because type is a literal in each envelope, the switch narrows data to the matching payload. If you handle every case, assert event is never in a default branch and TypeScript fails when a new event type is added.

You can also import the envelopes individually when you only handle one event:

type GameCompleted = components["schemas"]["WebhookEventGameCompleted"];

Keep generated code in sync

• Pin a version. Webhook payloads carry apiVersion (2026-10-20 today) and the REST API is versioned in the URL (/v1). Regenerate when dartpilot announces a change, and compare apiVersion before relying on a newly added field.
• Regenerate in CI. Run your generator against the live document on a schedule or in your build, then typecheck the result. The document changes only when dartpilot deploys, and the schedule catches otherwise silent drift.
• Commit the output. Vendoring the generated file keeps builds reproducible and makes API changes visible in code review. Add the raw openapi.json next to it if your generator runs offline.

Learn more

• API Reference — rendered from the same document.
• API Keys — create the key your generated client sends.
• Webhooks — event semantics, signing and retries.