---
title: "Generate from an API URL"
description: "From an OpenAPI or GraphQL URL to a typed package in a directory, with or without an account. Public and protected sources use the same flow."
url: https://typeship.dev/docs/guides/generate-from-a-url
markdown: https://typeship.dev/docs/guides/generate-from-a-url.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# Generate from an API URL

From an OpenAPI or GraphQL URL to a typed package in a directory, with or without an account. Public and protected sources use the same flow.

## Quick reference

```bash
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](https://typeship.dev/docs/projects/definition-patches), 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

| You see                                                    | It means                                              | Do                                                                                                                                                                 |
| ---------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fetch_error`                                              | typeship could not fetch the URL (auth, 404, timeout) | Check the URL; for a protected source, pass `headers` in the Definition input; or use an inline document: `--definition "{\"inline\":$(jq -Rs . < openapi.yaml)}"` |
| `spec_error` / `SPEC_INVALID`                              | the document is not a usable spec                     | [Debug a spec](https://typeship.dev/docs/guides/debug-a-spec)                                                                                                                          |
| `limits.omitted_operations = 0`                            | the plan has a ceiling, but this spec fits under it   | Nothing was omitted; do not claim the package is incomplete                                                                                                        |
| `limits.reason = "anonymous"` and `omitted_operations > 0` | the anonymous cap omitted operations                  | Offer `signup_url`; the resulting account's plan still applies                                                                                                     |
| `limits.reason = "free_plan"` and `omitted_operations > 0` | the keyed account is on the free plan                 | Open `upgrade_url`; a different key is not the fix                                                                                                                 |
| `RATE_LIMITED`                                             | more than 20 anonymous calls a minute                 | Wait the seconds named; or send a key                                                                                                                              |

> **For AI agents:** Run exactly the quick reference. If the response carries 
> 
> `claim.url`
> 
> , give it to the user. Report what was generated, where, and the warnings in one line.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)