# API Change

> API Change is an Agent Skill for development published in the software-mansion/smelter repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Run the full API change workflow after modifying types in smelter-api. Generates schemas, TypeScript types, and verifies everything is in sync.

- Skill name: `api-change`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/software-mansion/smelter/blob/HEAD/.claude/skills/api-change/SKILL.md
- Repository: software-mansion/smelter (705 GitHub stars when collected)

## SKILL.md

Run the API change workflow. All steps must pass before the change is considered complete.

## Steps

1. **Register new routes in OpenAPI spec**
   If a new route was added, ensure it is listed in the `#[openapi(paths(...))]` macro in `tools/src/bin/generate_from_types.rs`. Each route handler function must be referenced there for it to appear in the generated OpenAPI specification.

2. **Generate JSON schemas from Rust types**
   Run: `cargo run -p tools --bin generate_from_types`
   This generates `tools/schemas/scene.schema.json` and `tools/schemas/api_types.schema.json`.

3. **Generate TypeScript types from schemas**
   Run in `./ts`: `pnpm run generate-types`
   This generates `ts/smelter/src/api.generated.ts`.

4. **Build the TypeScript SDK to verify compatibility**
   Run in `./ts`: `pnpm i && pnpm build:all`

5. **Show a summary of all generated/changed files** so the user can review what was affected.

6. **Try to update SDK**:
   Update TypeScript SDK code if the generated types require manual adaptation.
   In most cases you will need to:
   - add/modify type in `ts/smelter` package e.g. `ts/smelter/src/types/input.ts`
   - add/modify mapping in `ts/smelter-core` package e.g. `ts/smelter-core/src/api/input.ts`. In most cases it will be just switching snake case to camel case, but consider if there are more idiomatic alternatives.
   - add/modify type in `ts/smelter-node/src/api.ts`.
   - add/modify type in `ts/smelter-web-client/src/api.ts`.
   Inform user if it's not obvious how the changes should be adapted.

---

Source: https://www.openparable.com/skill/development/api-change (OpenParable). Cite the canonical URL above.
