---
title: "Add inventory item via API key"
method: POST
path: "/v1/external/inventory"
tags: ["External"]
---

# Add inventory item via API key

`POST /v1/external/inventory`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/v1/external/inventory`
- Auth: none declared

## Headers

- `X-API-Key` string, nullable

## Request body

- InventoryItemIn: Body for POST /v1/inventory/. Either product_id or name must be set.
  - `product_id` integer, nullable: Link to a canonical Partle product. Use this when the user has a known product in mind. Either product_id or name must be set.
  - `name` string, nullable: Freeform name for items with no Partle product yet (e.g. one-off purchases from AliExpress, gifts). Either product_id or name must be set.
  - `status` 'owned' | 'wanted' | 'for_sale' | 'sold' | 'discarded'
  - `quantity` union: How many. Fractional ok (e.g. 2.5 m of cable).
    - number
    - string
  - `notes` string, nullable: Freeform multi-line text — the dumping ground for anything not modeled as a column: extra URLs, comments, where stored, condition narrative, purpose, source, history, log entries, etc. Markdown is fine. Don't ask for a 'second_url' or 'comment' field — put it here.
  - `acquisition_price` union: What you paid for it.
    - number
    - string
  - `acquisition_currency` string, nullable
  - `purchased_at` string, date, nullable: When you acquired it.
  - `asking_price` union: When status='for_sale'. Your asking price.
    - number
    - string
  - `asking_currency` string, nullable
  - `condition` string, nullable: Free string — typical values: new, like_new, good, fair, poor.
  - `external_link` string, nullable: Primary click-through URL for this item (one of: source listing, vendor page, manufacturer page). Exactly *one* — for additional URLs, drop them in `notes` as markdown links. UIs and cards display this one inline.
  - `external_id` string, nullable: Stable identifier from the source system, used as a dedup key. Per-user unique when set: same external_id can't appear twice for the same user. Format is up to the importer (e.g. `aliexpress:1005004714348221`, `amazon:order/3024.../line/1`, or a content hash). Leave null for handwritten items with no source.
  - `project` string, nullable: Tag for grouping (e.g. 'kitchen-renovation', 'formula-student'). Not strictly enforced.
  - `recipient_id` integer, nullable: If the item is for someone else (e.g. a gift, a household member's item), their user ID. Most items leave this null.

## Response `201`

Successful Response

- InventoryItemOut: Response shape from GET / POST / PATCH /v1/inventory/.
  - `id` integer, required
  - `user_id` integer, required
  - `product_id` integer, nullable
  - `status` 'owned' | 'wanted' | 'for_sale' | 'sold' | 'discarded', required
  - `name` string, nullable
  - `quantity` string, required
  - `notes` string, nullable
  - `acquisition_price` string, nullable
  - `acquisition_currency` string, nullable
  - `purchased_at` string, date-time, nullable
  - `asking_price` string, nullable
  - `asking_currency` string, nullable
  - `condition` string, nullable
  - `external_link` string, nullable
  - `external_id` string, nullable
  - `project` string, nullable
  - `recipient_id` integer, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `product` InventoryProductBasic: Compact product info embedded in inventory responses.
    - `id` integer, required
    - `name` string, required
    - `price` string, nullable
    - `currency` string, nullable

## Other responses

- `422`: Validation Error

---

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