▣ DEVELOPER TOOLS · SMART GENERATION

Convert JSON to Zod Schema API

Hosted on ApyHub

What it does

JSON to Zod Schema converts a non-empty JSON object into a Zod schema. Send JSON from a request body, an uploaded file, or a publicly accessible URL, and get back a generated schema as raw text, a downloadable .ts file, or a pre-signed S3 URL depending on the endpoint you choose.

Use mode to control the output style: annotated, clean, or explain. Use strict when you want stricter schema generation. The URL-based endpoints accept JSON resources served as application/json, text/plain, application/octet-stream, or binary/octet-stream, and the file-based endpoints require an uploaded JSON file with application/json mimetype.

This is useful when you need to turn sample API responses, fixture data, or exported JSON into a starting point for typed validation. Instead of hand-writing Zod by inspection, you can generate a baseline schema and then refine it in your codebase.

JSON to Zod Schema returns either the generated schema string, an assumptions list, and meta information for explain mode, or a downloadable/hosted schema file via data depending on the endpoint variant.

▣ ENDPOINT 01 / 09

POST

Convert JSON from URL to Zod schema (raw text or explain JSON)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-url-zod-raw

QUICKSTARTGUIDE

Quickstart

Convert a public JSON URL into a Zod schema by sending the JSON source URL in the request body.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-url-zod-raw?mode=annotated&strict=false" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/data.json"}'

What you'll get back

Returns a JSON object that may include:

meta объект with mode and strict
schema string containing the generated Zod schema
assumptions array of strings with any generation assumptions

{
  "meta": {
    "mode": "annotated",
    "strict": false
  },
  "schema": "z.object({ ... })",
  "assumptions": ["..."]
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Converts the JSON document available at a public URL into a Zod schema. The request takes a source url, and the response shape depends on the mode query parameter.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	ENUM	No	Allowed values: `annotated`, `clean`, `explain`.<br>Default: `annotated`.
strict	ENUM	No	Allowed values: `true`, `false`.<br>Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
url	String	Yes	Publicly accessible URL pointing to a JSON resource. The URL must return a content-type of `application/json`, `text/plain`, `application/octet-stream`, or `binary/octet-stream`, or the `Content-Disposition` / URL path must include `.json`. The JSON content must be a non-empty object.

Response

Returns a JSON object. The schema includes optional meta, schema, and assumptions fields. The documented output schema does not specify a single concrete success status code.

Parameter	Type	Mandatory	Description
meta	Object	No	Request metadata. Contains `mode` and `strict` when present.
meta.mode	ENUM	No	Allowed values: `annotated`, `clean`, `explain`.
meta.strict	Boolean	No	Whether strict mode was applied.
schema	String	No	The generated Zod schema as a string, without annotations.
assumptions	String Array	No	Human-readable list of assumptions applied during schema generation.

Notes

The mode query parameter defaults to annotated when omitted. The strict query parameter defaults to false when omitted.

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 02 / 09

POST

Convert uploaded JSON file to Zod schema (raw text or explain JSON)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-file-zod-raw

QUICKSTARTGUIDE

Quickstart

Upload a JSON file to generate a Zod schema. This minimal example uses the default request mode and strictness.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-file-zod-raw" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/file.json"

What you'll get back

Returns a JSON object with optional top-level meta, schema, and assumptions fields. meta is an object that may include mode and strict; schema is the generated Zod schema as a string; assumptions is an array of strings describing generation assumptions.

{
  "meta": {
    "mode": "annotated",
    "strict": false
  },
  "schema": "z.object({ ... })",
  "assumptions": ["..."]
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Converts an uploaded JSON file into a Zod schema. The request uploads a JSON file and can be tailored with query parameters to control the output mode and strictness.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	String	No	Allowed values: `annotated`, `clean`, `explain`<br>Default: `annotated`
strict	String	No	Allowed values: `true`, `false`<br>Default: `false`

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	JSON file to convert. The uploaded file must have mimetype `application/json` and must contain a non-empty JSON object.

Response

Returns a JSON object with meta and schema object/string fields, and an assumptions array field. The success response is documented in the schema as being returned when mode=explain.

Parameter	Type	Mandatory	Description
meta	Object	No	Metadata about the request options.
meta.mode	ENUM	No	Allowed values: `annotated`, `clean`, `explain`.
meta.strict	Boolean	No	Whether strict mode was applied.
schema	String	No	The generated Zod schema as a string (without annotations).
assumptions	String Array	No	Human-readable list of assumptions applied during schema generation (varies by `schemaMode`).

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 03 / 09

POST

Convert raw JSON body to Zod schema (S3 signed URL)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-raw-zod-url

QUICKSTARTGUIDE

Quickstart

Send a non-empty JSON object to convert it into a Zod schema, returning a pre-signed download URL.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-raw-zod-url?mode=annotated&output=sample-output&strict=false" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","role":"engineer"}'

What you'll get back

Returns a JSON object with a data string field. The data value is a pre-signed S3 URI for downloading the generated schema file.

{
  "data": "https://example.s3.amazonaws.com/generated-schema.ts?..."
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Converts a non-empty raw JSON request body into a Zod schema and returns a pre-signed S3 URL where the generated file can be downloaded. The output file is a .ts schema file by default, or a .json file when mode is explain.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	ENUM	No	Conversion output style.<br>Allowed values: `annotated`, `clean`, `explain`.<br>Default: `annotated`.
output	String	No	Output name used for the generated schema.<br>Default: `sample-output`.<br>Example: `my-schema`.
strict	ENUM	No	Strictness flag.<br>Allowed values: `true`, `false`.<br>Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
body	Object	Yes	Any non-empty JSON object sent as the request body.<br>Content-Type `application/json` is accepted, and `text/plain` is also accepted and parsed.<br>The body must not be empty; additional properties are allowed.

Response

Returns a JSON object with a data string field containing a pre-signed S3 URL for downloading the generated file. The data value is a URI pointing to the converted schema file, which is a .ts file by default or a .json file when mode is explain.

Parameter	Type	Mandatory	Description
data	String	Yes	Pre-signed S3 URL to the converted file.<br>URI format.<br>Points to the generated `.ts` schema file, or `.json` when `mode` is `explain`.

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

outputOPTIONAL

string

—

DEFAULT sample-output

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

Any non-empty JSON object sent as the request body with Content-Type application/json (or text/plain, which is also accepted and parsed). The body must not be empty.

▣ ENDPOINT 04 / 09

POST

Convert JSON from URL to Zod schema (downloadable file)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-url-zod-file

QUICKSTARTGUIDE

Quickstart

Convert a JSON file at a public URL into a Zod schema by sending the file URL in the request body.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-url-zod-file" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/data.json"}'

What you'll get back

Returns the Zod schema as a binary .ts file, or a JSON explain payload when mode=explain.

binary

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Converts JSON fetched from a publicly accessible URL into a Zod schema and returns it as a downloadable file. The request sends the source URL in the body, and the response is a binary file stream containing either a Zod schema .ts file or, when mode=explain, a JSON explain payload.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	String	No	Controls the output style. Allowed values: `annotated`, `clean`, `explain`. Default: `annotated`.
output	String	No	Output name. Default: `sample-output`. Example: `my-schema`.
strict	String	No	Controls strictness. Allowed values: `true`, `false`. Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
url	String	Yes	Publicly accessible URL pointing to a JSON resource. The URL must return `application/json`, `text/plain`, `application/octet-stream`, or `binary/octet-stream`, or the `Content-Disposition` / URL path must include `.json`. The JSON content must be a non-empty object.

Response

Returns a binary response containing a downloadable file. The output is a string with binary format; depending on mode, it is either a Zod schema .ts file or a JSON explain payload .json.

Parameter	Type	Mandatory	Description
value	String	Yes	Binary file content for the generated Zod schema or explain payload.

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

outputOPTIONAL

string

—

DEFAULT sample-output

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 05 / 09

POST

Convert JSON from URL to Zod schema (S3 signed URL)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-url-zod-url

QUICKSTARTGUIDE

Quickstart

Convert a public JSON URL into a Zod schema by sending the source URL in the request body.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-url-zod-url" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/data.json"}'

What you'll get back

Returns a JSON object with a data string field containing a pre-signed S3 URL for the generated schema file.

{
  "data": "https://s3.amazonaws.com/..."
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Converts JSON fetched from a publicly accessible URL into a Zod schema file and returns a pre-signed S3 URL for downloading the generated output. The request body supplies the source JSON URL, while query parameters control the conversion mode, output name, and strictness.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	ENUM	No	Conversion mode. Allowed values: `annotated`, `clean`, `explain`.<br>Default: `annotated`.
output	String	No	Output name. Default: `sample-output`.
strict	ENUM	No	Strictness flag. Allowed values: `true`, `false`.<br>Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
url	String	Yes	Publicly accessible URL pointing to a JSON resource. The URL must return a content-type of `application/json`, `text/plain`, `application/octet-stream`, or `binary/octet-stream`, or the `Content-Disposition` / URL path must include `.json`. The JSON content must be a non-empty object.

Response

Returns a JSON object with a data string field containing a pre-signed S3 URL for downloading the generated file. The URL points to the generated .ts schema file, or to a .json file when mode is explain.

Parameter	Type	Mandatory	Description
data	String	Yes	Pre-signed S3 URL to the converted file. S3 pre-signed URL for downloading the generated `.ts` schema file (or `.json` file when mode is `explain`).

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

outputOPTIONAL

string

—

DEFAULT sample-output

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

▣ ENDPOINT 06 / 09

POST

Convert uploaded JSON file to Zod schema (downloadable file)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-file-zod-file

QUICKSTARTGUIDE

Quickstart

Upload a JSON file to generate a Zod schema file.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-file-zod-file?mode=annotated&output=sample-output&strict=false" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/input.json"

What you'll get back

Returns a downloadable binary .ts file containing the generated Zod schema. If mode=explain, the same endpoint returns a JSON explain payload instead.

"<binary file>"

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Converts an uploaded JSON file into a downloadable Zod schema file. Depending on the mode query parameter, the response is either a .ts Zod schema file or a .json explain payload.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	String	No	Allowed values: `annotated`, `clean`, `explain`.<br>Default: `annotated`.
output	String	No	Default: `sample-output`.<br>Example: `my-schema`.
strict	String	No	Allowed values: `true`, `false`.<br>Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	Binary JSON file to convert. The uploaded file must have mimetype `application/json` and must contain a non-empty JSON object.

Response

Returns a binary downloadable file as the response body: a Zod schema .ts file, or a .json explain payload when mode=explain. The output schema is a single binary string value, so there are no named JSON fields in the success response.

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

outputOPTIONAL

string

—

DEFAULT sample-output

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 07 / 09

POST

Convert uploaded JSON file to Zod schema (S3 signed URL)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-file-zod-url

QUICKSTARTGUIDE

Quickstart

Upload a JSON file to convert it to a Zod schema.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-file-zod-url?mode=annotated&output=my-schema&strict=false" \
  -H "apy-token: $APY_TOKEN" \
  -F "file=@/path/to/file.json"

What you'll get back

Returns a JSON object with a data string field containing a pre-signed S3 URL to download the generated file.

{
  "data": "https://s3.amazonaws.com/..."
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Converts an uploaded JSON file into a Zod schema and returns a pre-signed S3 URL for downloading the generated file. The uploaded file is sent in the request body, and the conversion behavior can be adjusted with query parameters.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	String	No	Conversion output style. Allowed values: `annotated`, `clean`, `explain`. Default: `annotated`.
output	String	No	Output name. Default: `sample-output`. Example: `my-schema`.
strict	String	No	Strictness flag. Allowed values: `true`, `false`. Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
file	String	Yes	JSON file to convert. The uploaded file must have mimetype `application/json` and must contain a non-empty JSON object.

Response

Returns a JSON object with a data string field containing a URI. This is a pre-signed S3 URL for downloading the generated schema file; the file is a .ts schema file, or a .json file when mode is explain.

Parameter	Type	Mandatory	Description
data	String	Yes	Pre-signed S3 URL to the converted file. S3 pre-signed URL for downloading the generated `.ts` schema file (or `.json` file when mode is `explain`).

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

outputOPTIONAL

string

—

DEFAULT sample-output

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 08 / 09

POST

Convert raw JSON body to Zod schema (raw text or explain JSON)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-raw-zod-raw

QUICKSTARTGUIDE

Quickstart

Send a JSON object to generate a Zod schema. This minimal example uses the default annotated mode and strict=false.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-raw-zod-raw?mode=annotated&strict=false" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example","age":30}'

What you'll get back

Returns a JSON object with optional top-level meta, schema, and assumptions fields.

meta is an object with mode and strict.
schema is a string containing the generated Zod schema.
assumptions is an array of strings listing any assumptions made during generation.

{
  "meta": {
    "mode": "annotated",
    "strict": false
  },
  "schema": "z.object({...})",
  "assumptions": []
}

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Converts a raw JSON request body into a Zod schema representation. The request accepts a non-empty JSON object in the body, and the response shape depends on the selected mode.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	String	No	Allowed values: `annotated`, `clean`, `explain`.<br>Default: `annotated`.
strict	String	No	Allowed values: `true`, `false`.<br>Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
body	Object	Yes	Any non-empty JSON object. Must contain at least 1 property (`minProperties: 1`). Additional properties are allowed. Accepted with `Content-Type: application/json` or `text/plain`; the body is parsed either way.

Response

Returns a JSON object with meta, schema, and assumptions top-level fields when mode=explain. meta is an object with mode and strict; schema is a string containing the generated Zod schema; assumptions is an array of strings listing the assumptions used during generation.

Parameter	Type	Mandatory	Description
meta	Object	No	Metadata about the request options. Includes `mode` and `strict`.
meta.mode	ENUM	No	Allowed values: `annotated`, `clean`, `explain`.
meta.strict	Boolean	No	Whether strict mode was applied.
schema	String	No	The generated Zod schema as a string, without annotations.
assumptions	String Array	No	Human-readable list of assumptions applied during schema generation. This varies by schema mode.

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

Any non-empty JSON object sent as the request body with Content-Type application/json (or text/plain, which is also accepted and parsed). The body must not be empty.

▣ ENDPOINT 09 / 09

POST

Convert raw JSON body to Zod schema (downloadable file)

http://localhost:8080/apyhub/convert-json-to-zod-schema/json-raw-zod-file

QUICKSTARTGUIDE

Quickstart

Convert a JSON object into a downloadable Zod schema file with the default annotated output.

curl -X POST "http://localhost:8080/apyhub/convert-json-to-zod-schema/json-raw-zod-file" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-schema","version":1}'

What you'll get back

Returns a binary .ts file containing the generated Zod schema. The output schema is a single binary value, so there is no JSON wrapper to display.

TRY ITLIVE · 50 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Converts a non-empty raw JSON request body into a Zod schema. Depending on the mode query parameter, it returns either a downloadable .ts Zod schema file or a .json explain payload.

Query Parameter(s)

Attribute	Type	Mandatory	Description
mode	String	No	Allowed values: `annotated`, `clean`, `explain`.<br>Default: `annotated`.
output	String	No	Output file base name.<br>Default: `sample-output`.<br>Example: `my-schema`.
strict	String	No	Allowed values: `true`, `false`.<br>Default: `false`.

Request Body

Parameter	Type	Mandatory	Description
body	Object	Yes	Any non-empty JSON object sent as the request body. The body must not be empty. Accepts `application/json` or `text/plain`, which is also parsed.

Response

Returns a binary response: a downloadable Zod schema (.ts) file, or a JSON explain payload (.json) when mode=explain. The output schema is a single binary string value, so there are no JSON fields to describe.

Parameter	Type	Mandatory	Description
response	String	Yes	Binary file content for the generated Zod schema or explain payload, depending on `mode`.

Query parameters

Name

Type

Description

modeOPTIONAL

string

annotated · clean · explain

—

DEFAULT annotated

outputOPTIONAL

string

—

DEFAULT sample-output

strictOPTIONAL

string

true · false

—

DEFAULT false

Body

Name

Type

Description

bodyREQUIRED

object

Any non-empty JSON object sent as the request body with Content-Type application/json (or text/plain, which is also accepted and parsed). The body must not be empty.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.