---
title: "Create Component"
method: POST
path: "/v1/components"
tags: ["v1", "components"]
---

# Create Component

`POST /v1/components`

## Request

- Base URL: `https://thrustlab.com`
- URL: `https://thrustlab.com/v1/components`
- Auth: HTTP bearer

Create a custom component scoped to the authenticated user.

Body fields: `type` (required; motor|battery|propeller), `name` (required,
1-255 chars), `spec_json` (required; type-specific map).

Every type's product-required spec_json fields are enforced at this
boundary (2026-07-16); a missing field is a 400 naming the field, its
meaning, and its units. Motors need kv, n, R, weight, diameter, length,
u_nominal, iq_nominal, and one of iq_max/power_max. Propellers need
diameter, pitch, weight, rotation, and parallel radius/chord/twist
station arrays. Batteries need a known chemistry plus, for a
physical pack, bounding-box dimensions, cell layout, capacity, mass, and
one internal-resistance figure (form_factor is derived from chemistry
when omitted and stored); a source needs series_cells and source_voltage.

Returns the new component resource (201) with source="user",
visibility="private", and user_id set to the caller. The response may
carry a non-blocking `warnings` list when a spec value looks physically
implausible (e.g. motor R far outside the expected range for its Kv,
weight, and diameter — often a milliohm/ohm mix-up or a per-phase value
where phase-to-phase is expected). A warning never rejects the write.

A motor is rejected with HTTP 400 naming `spec_json.iq_nominal` when
`iq_nominal` is 40% or more of `iq_max`. For a motor with only `power_max`,
the same error applies when `u_nominal` times `iq_nominal` is 30% or more of
`power_max`. This almost certainly means a rated or maximum current was
entered as no-load current. It would make the simulator overstate the
motor's own losses, raising current and lowering efficiency.

## Request body

- ComponentCreateBody
  - `name` string, required
  - `spec_json` object, required
  - `type` string, required

## Response `201`

Successful Response

- ComponentWriteResponse: Create/patch response: the component resource plus optional warnings. ``warnings`` is omitted (null) when every spec value looks plausible.
  - `base_component_id` string, uuid, nullable, required
  - `created_at` string, date-time, required
  - `id` string, required
  - `name` string, required
  - `object` string
  - `source` string, required
  - `spec_json` object, required
  - `type` string, required
  - `updated_at` string, date-time, required
  - `user_id` string, uuid, nullable, required
  - `visibility` string, required
  - `warnings` ComponentWriteWarning[], nullable
    - `code` string, required
    - `message` string, required
    - `object` string
    - `param` string, required

## Other responses

- `422`: Validation Error

---

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