Create a new product listing on Partle.
Authenticated. Prefer **OAuth**: connect once via the consent flow on
claude.ai (or any MCP client that supports OAuth) and the bearer token
is attached automatically — no `api_key` parameter needed. **Fallback**:
pass an `api_key` (prefix `pk_`, generate at /account) for programmatic
or non-OAuth clients.
Required OAuth scope: `products:write`.
Use when the user wants to add an item for sale. For edits to an
existing product, use `update_product` instead.
**Images.** This tool creates text fields only — no image arg. Do
**not** try to pass image bytes through a tool argument; phone-sized
payloads blow past conversation context limits.
The response includes a one-shot ``upload_url`` (signed, ~15 min TTL,
bound to this product and your authenticated user). To attach an
image from your code-execution sandbox, do **one** PUT request — no
auth headers needed, the URL itself carries the credential:
requests.put(result["upload_url"],
data=open("/path/to/photo.jpg", "rb").read(),
headers={"Content-Type": "image/jpeg"})
The bytes flow Python → HTTP body → Partle, never through the
conversation. The URL works once and expires fast.
Alternative if you don't have local bytes but have a public image URL:
call ``upload_product_image(product_id, image_url=...)`` instead.
**Duplicate prevention.** Same user, same product name (case- and
whitespace-insensitive) returns 409 with `existing.id`, `existing.url`,
**and a fresh `upload_url`** for that existing product — so if the
user is just retrying with a photo, you can attach it directly to the
existing listing without having to create or pick anything new. You
can also call `update_product` to change fields. Don't retry blindly.
**Idempotency.** Pass `idempotency_key` (any unique string per logical
create — UUID or hash of the source listing) and a retry after a
network failure returns the original response instead of creating a
duplicate. Reusing a key with a different payload is a 422.
Args:
name: Product name. Required, 1–200 chars.
description: Long-form product description. Optional.
price: Price in whole currency units, **not** cents (e.g. ``15.99``
means €15.99). Max 100000. Omit for "ask the seller".
currency: Currency symbol. Defaults to `€`. Use `$`, `£`, etc.
url: Link to the merchant's product page. Optional but recommended.
store_id: ID of the store this product belongs to. Omit for a
personal listing not tied to any store.
listing_type: ``in_stock`` (default) when the seller has the item
and it can be bought now. ``tentative`` when they do not stock
it and want to measure interest first — such a listing is kept
out of normal search results and instead collects "I need this"
presses. Only use ``tentative`` if the user explicitly said they
are gauging demand; an item that is merely out of stock today is
still ``in_stock``. If the user is looking to *buy* something
nobody sells, use `create_buy_request` instead — that is the
demand side and it is a different tool.
idempotency_key: Optional retry-safety token. Unique per logical
create. Send the same key on retries to get the same response.
api_key: Optional API key (`pk_*`, generate at /account).
Used when there is no OAuth token, and also when the OAuth
token lacks the required scope — an explicitly passed key
overrides an ambient token that is scoped too narrowly.
An invalid or revoked token still fails regardless. Omit when using OAuth.
Returns:
The created product record including its new `id` and canonical
`partle_url`. Share `partle_url` with the user. Returns
``{"error": ...}`` on auth, dedup, or validation failure (dedup
also returns ``{"existing": {"id", "name", "url"}}``).