Add an item to the caller's personal inventory.
Authenticated. Required OAuth scope: `inventory:write`.
One creation tool covers all lifecycle states — set ``status`` based
on the user's intent: "I bought" → ``owned``, "I want" → ``wanted``,
"I'm selling" → ``for_sale``. Either ``product_id`` (linked to an
existing Partle product) or ``name`` (freeform) must be set.
**Not idempotent** — each call creates a new row.
Args:
name: Freeform name for items not yet linked to a Partle product.
Either ``name`` or ``product_id`` must be set.
product_id: Link to a canonical Partle product.
status: Lifecycle. One of: ``owned``, ``wanted``, ``for_sale``,
``sold``, ``discarded``. Default ``owned``.
quantity: How many. Fractional allowed. Default 1.
notes: 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.
Markdown is fine. **Put extra URLs here, not in another field.**
acquisition_price: What the user paid.
acquisition_currency: Currency of acquisition_price.
purchased_at: ISO date (YYYY-MM-DD) when it was acquired.
asking_price: When status=for_sale, asking price.
asking_currency: Currency of asking_price.
condition: Free string — typical: ``new``, ``like_new``,
``good``, ``fair``, ``poor``.
external_link: **Primary** click-through URL only (source listing,
vendor page, manufacturer page). Exactly one. Additional URLs
go in ``notes`` as markdown links.
external_id: Stable identifier from the source system, used as a
**dedup key**. Per-user unique when set — same external_id
can't appear twice for one user. Format is up to you (e.g.
``aliexpress:1005004714348221``, ``amazon:order/3024.../line/1``,
content hash). Leave null for handwritten items.
project: Tag for grouping (e.g. "kitchen-renovation").
api_key: Legacy/fallback auth.
Returns:
The newly-created inventory row (with embedded `product` if
linked), or ``{"error": ...}`` on auth/validation failure.