Generate from an API URL

Quick reference

npm install -g @typeship-ax/cli                                                   # or npx -y @typeship-ax/cli@latest ...
typeship generate run --definition '{"url":"https://api.acme.example.com/openapi.json"}' \
  --target typescript-sdk --out sdk/acme                         # no key needed
cd sdk/acme && npm install && npm test                                    # TypeScript: build + one smoke test per operation

With a key in TYPESHIP_TOKEN, the same command uses the account's plan: free still generates the first 25 operations, while paid plans generate the whole spec.

Why these commands

generate run is stateless. It runs the generator on the spec and returns the package. Nothing is stored, so it is the right call for a one-off, an evaluation, or a script that commits the output itself. --out writes the files where you point it and prints a summary (meta, warnings, limits, claim) instead of the file contents; without --out the whole package comes back as JSON.

Anonymous is fine to start. Without a key the first 25 operations generate, 20 calls a minute per address. The response's limits object says how many operations were left out and whether the cap is anonymous or belongs to the free plan; claim.url is a link that turns this run into a linked project once you sign in, so nothing is lost by starting without an account.

Protected source URLs stay write-only. Put the source credential inside the Definition input, for example --definition '{"url":"https://api.acme.example.com/openapi.json","headers":{"Authorization":"Bearer …"}}'. typeship sends those headers while fetching an OpenAPI document or introspecting a GraphQL endpoint. Stateless generation does not retain them. A linked project stores them write-only, never returns them through the API, and never writes them into generated artifacts.

Pick one Target. --target accepts typescript-sdk, python-sdk, go-sdk, cli, and mcp. One-shot generation produces exactly one focused package. Create a linked project to keep any combination, or all five, current in independent destinations.

Read the warnings once. They name what the spec left out or what was approximated (a relative server URL, a security scheme that did not map, an operation without an id). Most are fixed in the spec or with a Definition patch, not by hand in the output.

Verify before you depend on it. A TypeScript package builds and ships one smoke test per operation (npm test against the spec's shapes, no network); Python compiles (python -m compileall); Go builds (go build ./...). The package's own AGENTS.md and api.md are the reference for what you generated.

What can go wrong