---
title: "Attach a form or selector with a mapping"
method: POST
path: "/v1/streams/{streamId}/sources"
tags: ["streams"]
---

# Attach a form or selector with a mapping

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

## Request

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

If the stream has no schema yet, the attached form provides version 1 (copied from its published schema, its inferred draft, or the fields seen in recent submissions) and an identity mapping is used when `mapping` is omitted — so attaching the first form never needs a hand-written schema. Fails 422 stream_schema_missing if neither the stream nor the form has any fields to work from. Fails 422 mapping_incomplete (with the missing fields listed) if the mapping does not cover every field the stream's schema requires — a form can't join a stream it can't feed.

## Path parameters

- `streamId` string, required

## Request body

- object
  - `form_id` string: One Form feeding this Stream. Mutually exclusive with `selector`.
  - `selector` string: A dynamic Form source: non-empty `tag:<tag>` or `project:<project_id>` without leading or trailing whitespace after `:`. Mutually exclusive with `form_id`.
  - `mapping` object: Keyed by the stream schema's field names. Each entry is exactly one of `from` (copy a field from the form's data), `const` (a fixed value) or `expr` (a JSONata expression), plus an optional `default`. Every required field in the stream's schema must be covered or this call fails 422 mapping_incomplete.

## Response `201`

attached

- StreamSource
  - `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)