---
title: "Publish a new schema version"
method: POST
path: "/v1/forms/{formId}/schema"
tags: ["forms"]
---

# Publish a new schema version

`POST /v1/forms/{formId}/schema`

## Request

- Base URL: `https://postbag.dev`
- URL: `https://postbag.dev/v1/forms/{formId}/schema`
- Auth: HTTP bearer

Schemas are immutable versions — this always creates version N+1, never mutates an existing one.

## Path parameters

- `formId` string, required

## Request body

- object
  - `json_schema` object, required: JSON Schema draft 2020-12 describing the submission data. `required` drives drift detection and mapping completeness.
  - `ui` object: Per-field rendering hints keyed by field name (label, placeholder, widget, options, order) — used to render embed snippets.
  - `changelog` string: A short human note on what changed in this version, shown in the version history.

## Response `201`

published

- SchemaVersion
  - `json_schema` object, required
  - `ui` object
  - `changelog` string
  - `version` integer
  - `inferred` boolean
  - `created_at` string
  - `created_by` string

## Other responses

- `400`: Error
- `401`: Error
- `403`: Error
- `404`: Not found
- `409`: Error
- `422`: Error

---

[API](https://skmtc.dev/postbag/apis/postbag-api.md) · [All operations](https://skmtc.dev/postbag/apis/postbag-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postbag/apis/postbag-api/revisions/3da976524695?raw)