---
title: "Publish a new stream schema version"
method: POST
path: "/v1/streams/{streamId}/schema"
tags: ["streams"]
---

# Publish a new stream schema version

`POST /v1/streams/{streamId}/schema`

## Request

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

Schemas are immutable versions — this always creates version N+1. Re-validates every attached source's mapping against the new schema and returns the updated mapping statuses alongside it.

## Path parameters

- `streamId` 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

- object
  - `schema` SchemaVersion, required
    - `json_schema` object, required
    - `ui` object
    - `changelog` string
    - `version` integer
    - `inferred` boolean
    - `created_at` string
    - `created_by` string
  - `mappings` StreamSource[], required
    - `id` string, required
    - `form_id` string
    - `selector` string
    - `mapping` object
    - `mapping_status` 'valid' | 'incomplete'
    - `missing` string[]
    - `stream_schema_version` integer

## 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)