---
title: "Upsert Schema Fields"
method: POST
path: "/api/connections/{connection_id}/schemas/{schema_id}/fields"
tags: ["Schemas"]
---

# Upsert Schema Fields

`POST /api/connections/{connection_id}/schemas/{schema_id}/fields`

Creates or updates user-defined fields on a schema, matched by field_id.

Fields are matched by `field_id`. Reusing an existing `field_id` updates that
field; using a new `field_id` creates a new user-defined field.

This makes the endpoint safe to retry when you are intentionally upserting the
same field definitions. It is not a patch-by-position operation.

If some fields succeed and others fail, the endpoint can return a partial
success response. Validate the response status and message rather than assuming
the whole batch was applied uniformly.

## Path parameters

- `connection_id` string, uuid, required — Unique identifier of the connection.
- `schema_id` string, required — Identifier of the schema the fields belong to.

## Headers

- `X-Polytomic-Version` string

## Request body

- UpsertSchemaFieldRequest
  - `fields` UserFieldRequest[], nullable — Fields to create or update on the schema. Existing user-defined fields with the same field_id are replaced.
    - `example` unknown
    - `field_id` string, required — Stable identifier for the user-defined field. Reuse an existing field_id to update a field in place.
    - `label` string, required — Human-readable label shown to users selecting this field in the app.
    - `path` string, nullable — JSON path expression that extracts the field's value from the source record. Required for nested or computed fields; omit for top-level fields.
    - `type` string, required — Polytomic type of the field (e.g. string, integer, boolean).

## Response `202`

Accepted

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/polytomic/apis/polytomic-api.md) · [All operations](https://skmtc.dev/polytomic/apis/polytomic-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/polytomic/polytomic-api/revisions/6c3b7c51e463/schema)