Typed API and OpenAPI

api gives every action an HTTP route, an OpenAPI 3.1 document and a typed client from one schema. Reach for it when a partner, a mobile app or a script calls your app over HTTP.

api:
  base: /api
  actions: src/actions.ts
  openapi:
    serve: false
    include: ["*"]
    title: Acme API
  snapshot: api/openapi.json
  idempotency:
    require: [destructive]
pagination:
  key: PAGINATION_KEY                  # secret that signs list cursors

import { api } from "mainsdk/api";
import { refundOrder } from "./actions/orders";

const doc = api.openapi([refundOrder], { include: ["orders.*"] });   // OpenAPI 3.1

import assert from "node:assert/strict";
import { action } from "mainsdk";
import { api } from "mainsdk/api";
import { s } from "mainsdk/schema";

const ping = action({
  name: "ping.get",
  intent: "Say pong",
  input: s.object({}),
  output: s.object({ pong: s.boolean() }),
  risk: "read",
  http: { method: "GET", path: "/ping", cache: { scope: "public", maxAge: "60s" } },
  run: () => ({ pong: true }),
});
const handler = api.handler({ actions: [ping] });
const res = await handler(new Request("http://app.test/api/v1/ping"));
assert.equal(res?.status, 200);

api:
  driver: builtin

Quick start

import { action } from "mainsdk";
import { s } from "mainsdk/schema";

export const refundOrder = action({
  name: "orders.refund",
  intent: "Refund an order the signed-in user owns",
  input: s.object({ orderId: s.string().uuid(), reason: s.enum(["damaged", "late"]) }),
  output: s.object({ refundId: s.string(), status: s.enum(["pending", "done"]) }),
  risk: "destructive",
  http: { method: "POST", path: "/orders/{orderId}/refund" },
  run: async ({ input }) => ({ refundId: `r_${input.orderId}`, status: "done" as const }),
});

npx mainsdk api openapi --out api/openapi.json
npx mainsdk api client --out src/acme-api.ts

Configuration

schema: 1
api:
  base: /api                    # public routes are /api/v<major>/…
  actions: src/actions.ts       # the module that exports the actions; the CLI and check load it
  openapi:
    serve: false                # true serves /.well-known/openapi.json, unauthenticated
    include: ["*"]              # action name globs in the document and the client
    title: Acme API
  snapshot: api/openapi.json    # the committed document that check and api diff compare against
  idempotency:
    require: [destructive]      # risks that must send Idempotency-Key

What you get

api is a core module with no drivers (spec app-api, 0.3): import it from mainsdk/api. Mount api.handler({ actions, ... }) in front of your app's own routes, or pass it as the api option of an adapter. It answers a request for a path it owns and returns undefined for any other. Set idempotency.ttl (24h by default) in the handler options to change how long a key is remembered.

• Versioned routes, <base>/v<major>/…, from each action's http mapping. A bad mapping is refused at start.
• An OpenAPI 3.1 document that is the same bytes for the same actions, so a snapshot diffs cleanly.
• A one-file typed client with problem errors, retries, idempotency keys and paging helpers.
• An output check: a value that fails its output schema is never sent.

Examples

Call the app from another service

mainsdk api client writes one file with no imports and only the global fetch. Call it like any typed function:

import { createClient } from "./acme-api.ts";

const acme = createClient({ baseUrl: "https://acme.app", auth: { apiKey: process.env.ACME_KEY ?? "" } });
const orderId = "2c8b1c1e-7d7e-4b8e-9d0a-5d1a3a8f4a11";
const r = await acme.orders.refund({ orderId, reason: "late" }, { idempotencyKey: "refund-8812" });

Every non-2xx answer and every network failure throws an ApiError with status, code, fix, retryable and, for input errors, the errors paths.

Read every page of a list

import { createClient } from "./acme-api.ts";

const acme = createClient({ baseUrl: "https://acme.app" });
for await (const order of acme.orders.list.all({ status: "open" })) {
  console.log(order.id);
}

Stop breaking changes in CI

npx mainsdk api diff --base origin/main

api diff lists breaking changes against the snapshot. A breaking change in a major version that has already shipped fails with MAIN-API-0012. To change a shipped major, add a new one with version: 2 and keep the old one until its sunset date.

Make writes safe to retry

A write whose risk is listed under api.idempotency.require needs an Idempotency-Key header, or the call fails with MAIN-API-0005. The same key with a different input returns 422 (MAIN-API-0002). A key whose first request is still running returns 409 and is retryable (MAIN-API-0003). The client sends the key for you when you pass idempotencyKey.

Retire an old major version

deprecated: { sunset: "2027-06-30" }   // after this date the old major answers 410

A call to a major after its sunset date fails with MAIN-API-0006. Until then the old major keeps working.

Errors and checks

Swapping drivers

There are no drivers. The document, the client and the routes are generated from the same actions that MCP and agents use, so nothing needs a second definition.

Testing

The handler runs in process, so route tests need no server. Call it with a Request and assert on the Response; createTestApp() supplies the app state the actions use.

import assert from "node:assert/strict";
import { action } from "mainsdk";
import { api } from "mainsdk/api";
import { s } from "mainsdk/schema";

const ping = action({
  name: "ping.get",
  intent: "Say pong",
  input: s.object({}),
  output: s.object({ pong: s.boolean() }),
  risk: "read",
  http: { method: "GET", path: "/ping", cache: { scope: "public", maxAge: "60s" } },
  run: () => ({ pong: true }),
});
const handler = api.handler({ actions: [ping] });
const res = await handler(new Request("http://app.test/api/v1/ping"));
assert.equal(res?.status, 200);

See the Testing kit.

Security and privacy

• output is also the list of fields allowed to leave the app. Keep it strict.
• A risk you list under idempotency.require cannot be retried into a double write.
• openapi.serve is off by default, so the document stays private until you turn it on.

FAQ

Is the OpenAPI document public? No. openapi.serve is off by default, and when it is on it lists only the actions in include.

Do I write the routes by hand? No. Each action's http mapping, or the default POST <base>/v<major>/actions/<name>, becomes a route.

Can I change a shipped version? Not in a way that breaks clients. Add version: 2 and keep the old major until its sunset date.

Reference

api comes from mainsdk/api. The paging and inbound helpers below are in mainsdk.

Next

• Actions: the single definition every door uses.
• API keys: who may call the routes.
• Schema: the input and output schemas.
• Typed API guide: publish the API and client for a partner.
• Call your API from React: hooks for the generated client.