Generate from a URL

Use a specification URL when your spec is hosted outside GitHub. You can generate one package without signing in or save the URL in a Project to track changes.

You need Node.js 20 or later and npm for these commands. The URL must be publicly reachable; credentials can protect the content, but they do not make a private network address reachable. See source boundaries.

Generate a package

Choose one Target and an output directory. This command uses the hosted sample; replace its URL with your own when ready:

typeship packages generate \
  --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' \
  --target '{"type":"typescript_sdk"}' \
  --out ./generated/typescript

Inspect the summary for warnings and coverage.omitted, then follow the package's README. For this TypeScript Target, validate it locally:

cd generated/typescript
npm install
npm test

The generated TypeScript tests check operation shapes without calling your API. For Python, compile the package with python -m compileall .; for Go, run go build ./.... Test an authenticated read separately before depending on the package.

Configure source access

packages generate creates one package and saves no Project. --target accepts a JSON descriptor whose type is cli, mcp, typescript_sdk, python_sdk, or go_sdk. --out writes the files and prints a summary; omit it to receive the files as JSON.

Anonymous generation includes the first 25 operations and allows 20 requests per minute per IP. With TYPESHIP_TOKEN, generation uses your organization's plan; a Free key still has the 25-operation cap. Check Plans and limits before assuming all operations were included.

For a protected URL, include fetch headers in the Spec input:

{
  "url": "https://api.parcel.example/openapi.yaml",
  "headers": { "Authorization": "Bearer <source-token>" }
}

This is an illustrative input for the fictional Parcel API. Replace the URL and credential, then pass the object through --spec. These headers fetch or introspect the source; they do not authenticate your generated client's requests. Headers remain on the configured origin and are stripped after a cross-origin redirect.

Typeship uses source credentials only to fetch your Spec. The API and generated packages never expose them. Projects store them write-only for later fetches.

An anonymous URL run may return claim.url. Open it and sign in within seven days to turn the recipe into a Project. Inline runs, runs authenticated to Typeship, and anonymous runs with source headers do not receive claim links. See What is stored for the claim’s contents and lifetime.

What can go wrong

To track this source over time, create a Project using the Quickstart. Automatic generation is on by default; see Keep a package current.