Publish your actions as a typed API

Your app already has actions. This guide publishes them over HTTP as an OpenAPI 3.1 document and a typed client, so a partner can call them without reading your code. It takes about 20 minutes.

Spec app-api, for 0.3. Run npx mainsdk api --help for the commands your version ships.

You need

• A MainSDK app with at least one action (see Expose an action to agents).
• An output schema on each action you want to publish. Without one, the document types the output as unknown.

1. Turn the API on

api:
  base: /api
  openapi:
    serve: false
    include: ["orders.*"]         # only these actions are published
    title: Acme API
  snapshot: api/openapi.json
  idempotency:
    require: [destructive]

include is a list of action name globs. Actions outside it stay private.

2. Mark the write that must not repeat

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: "pending" as const }),
});

A destructive action now needs an Idempotency-Key header. A repeat with the same key returns the first answer.

3. Write the document and the client

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

Commit both files. api/openapi.json is the snapshot that mainsdk check compares against.

4. Call it from a script

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";
await acme.orders.refund({ orderId, reason: "late" }, { idempotencyKey: "refund-8812" });

5. Stop breaking changes in CI

npx mainsdk api diff --base origin/main

Add it to the pull request job. A breaking change in a major version that has shipped fails with MAIN-API-0012. To change it, add version: 2 to the action and keep version 1 until its sunset date.

Check it worked

• mainsdk check passes, and api/openapi.json matches the code.
• Calling the refund twice with the same Idempotency-Key returns the same answer and writes once.
• Calling it without the key returns 400 with MAIN-API-0005.
• Removing a field from output makes api diff fail.

If it fails

• MAIN-API-0011: the snapshot is stale. Run api openapi again and commit the result.
• MAIN-API-0010: a schema has no JSON Schema. Use a schema from mainsdk/schema.

Prompt for your coding agent

Publish the actions under orders.* as an OpenAPI document and a typed client using MainSDK's api interface. Make orders.refund a destructive write that requires Idempotency-Key, keep openapi.serve off, and add mainsdk api diff to the pull request job.