Generate TypeScript Types from curl Output

You hit an API with curl, get back a wall of JSON, and now you need TypeScript types for it. The usual path is copying the response, opening a browser tool or writing interfaces by hand, then pasting the result into your project. That is three steps too many.

The @maisondigital/jsontoschema CLI accepts stdin. Combined with curl, you get types in one command.

The one-liner

curl -s https://api.example.com/users/1 | npx @maisondigital/jsontoschema --typescript

This fetches the response, pipes it into the converter, and prints TypeScript interfaces to stdout. Redirect to a file and you have a type definition ready to import:

curl -s https://api.example.com/users/1 \
  | npx @maisondigital/jsontoschema --typescript \
  > src/types/user.ts

Why this beats manual typing

A typical API response has nested objects, optional fields, and arrays with inconsistent items. Writing that by hand is slow and error-prone. Consider a response like this:

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "address": {
    "street": "123 Main St",
    "city": "Portland",
    "zip": "97201"
  },
  "orders": [
    { "id": 1, "total": 29.99, "status": "shipped" },
    { "id": 2, "total": 14.50, "status": "pending", "tracking": "1Z999AA10" }
  ]
}

The CLI produces interfaces that handle the tracking field appearing in only some order objects. It marks tracking as optional because it is missing from the first array item. You would need to inspect every array element to catch that by hand.

Schema mode for documentation

If you need a structural overview instead of types, drop the --typescript flag:

curl -s https://api.example.com/users/1 | npx @maisondigital/jsontoschema

The output is a compact schema showing field names, types, and optionality. Useful for pasting into API docs, README files, or LLM prompts where token count matters.

Fitting it into a workflow

Two patterns work well:

Exploratory typing. You are integrating a new API. Hit each endpoint with curl, pipe through the CLI, and generate a types file per resource. You get full coverage in minutes instead of hours.

Keeping types fresh. Add the curl | jsontoschema command to a Makefile or npm script. When the API changes, re-run it and diff the output against your existing types. Changes in the JSON structure show up as changes in the generated interfaces.

types/user.ts:
	curl -s https://api.example.com/users/1 \
	  | npx @maisondigital/jsontoschema --typescript > $@

Run make types/user.ts, commit the result, and your types stay in sync with the real API.

When to write types by hand

Generated types reflect the shape of the data you feed in. If the API has fields that only appear under certain conditions, you need sample responses that include those fields. For endpoints with complex conditional logic, a hand-written type with comments explaining the variants is still the better choice.

For the common case of "I have a JSON response and need types now," the CLI handles it. Paste the response or pipe it from the converter.