Search Partle's product catalog by name or description.

Use this when the user asks to find a specific product or browse products matching a query. Prefer this over search_stores when the intent is product-led ("find a drill") rather than store-led ("what stores are near Madrid"). Use get_product afterwards if the user wants full details for one specific result.

Read-only. No authentication. Rate-limited to 100 requests/hour per IP.

Args: query: Free-text search term (e.g. "wireless headphones", "cerrojo FAC", "drill bit"). Required even in semantic mode. min_price: Lower bound on price in EUR. Omit for no lower bound. max_price: Upper bound on price in EUR. Omit for no upper bound. tags: Comma-separated tag filter (e.g. "electronics,bluetooth"). Tags are AND-ed together. store_id: Restrict results to a single store. Use the integer id field from search_stores results. sort_by: One of price_desc, name_asc, newest, oldest. Omit to use the default search-relevance ranking. semantic: When True, runs a vector / cross-language search. Set this when the user's query may not match the listing language — e.g. "drill" in English will also surface "taladro" (Spanish) and "Bohrmaschine" (German). Pure-English catalogs benefit less. limit: Maximum results (1–100, default 20). Larger limits are slower and may exceed the rate budget faster. offset: Skip this many results before returning. Use for pagination (offset += limit on each follow-up call).

Returns: {"result": [Product, …]}. Each product includes id, name, price, currency, url, description, store (id / name / country), images, tags, and a canonical partle_url. Always share partle_url with the user so they can view the listing.

Get the full record for a single product by its numeric ID.

Use this after search_products returns a candidate the user is interested in, when you need fields that aren't in the search summary (full description, all images, expiration, sold status). Don't loop get_product over many search results — re-search with tighter filters instead.

Read-only. No authentication.

Args: product_id: The integer id from a product returned by search_products or shown on a Partle product page URL.

Returns: A single product object with all fields, including the canonical partle_url to share with the user.

Search or list stores in the Partle marketplace.

Use this when the user asks store-led questions ("what hardware shops are in Madrid?") rather than product-led ones (use search_products for that). Pass no query to browse the whole catalog.

Read-only. No authentication. Rate-limited to 100 requests/hour per IP.

Args: query: Free-text search over store name and address. Omit to list all stores in default order. limit: Maximum results (1–50, default 20).

Returns: {"result": [Store, …]}. Each store includes id, name, address, country, lat/lon (when geocoded), homepage, and type. Pass id to search_products(store_id=…) to filter the product catalog by that store.

Get the full record for a single store by its numeric ID.

Use this after search_stores to retrieve fields that aren't in the search summary (full address, owner profile, contact details). For a list of products in that store, call search_products(store_id=…) instead — this tool returns store metadata only.

Read-only. No authentication.

Args: store_id: The integer id from a store returned by search_stores.

Returns: A single store object with all fields.

Get top-level Partle platform statistics.

Use this for size questions ("how big is Partle?", "how many stores does Partle cover?"). Returns aggregate counts only — no per-product or per-store data.

Read-only. No authentication. Cheap, but doesn't change often — cache in long-running agents.

Returns: {"total_products": int, "total_stores": int, "last_updated": str, "api_version": str, "description": str}.

Send freeform feedback about your experience using Partle.

Use this when you encounter a confusing tool description, a broken response, missing data, or anything you'd want the maintainers to know. Especially valuable for AI agents — your feedback becomes a signal we use to tune the API.

Not idempotent (each call adds a record). Don't loop. No PII required.

Args: feedback: Freeform text up to 5000 characters. Be specific — name the tool, the input that was confusing, and what you expected.

Returns: The created feedback record with timestamp.

Create a new product listing on Partle. Requires an API key.

Use this when the user wants to add an item for sale. Each call creates a new record — never call twice with identical input expecting only one record (it is not idempotent). For updates to existing products, use update_product.

Args: api_key: Partle API key, prefix pk_. Generate at https://partle.rubenayla.xyz/account. 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.

Returns: The created product record including its new id and canonical partle_url. Share partle_url with the user.

Update fields on an existing product. Requires an API key.

Only fields you pass are changed; omitted fields are preserved. Idempotent — calling twice with the same input yields the same final state. For creating a new listing, use create_product instead.

The API key must own the product. Trying to update someone else's product returns a 403/404.

Args: api_key: Partle API key (prefix pk_). product_id: ID of the product to update. Get from create_product's return value, get_my_products, or search_products. name: New product name. Omit to leave unchanged. description: New description. Omit to leave unchanged. price: New price in whole currency units (e.g. 15.99 = €15.99). currency: New currency symbol. url: New merchant URL.

Returns: The updated product record (full, not just the changed fields).

Permanently delete a product listing and all its images. Destructive.

Use only when the user explicitly asks to remove a listing they own. Cannot be undone — there is no soft-delete or trash bin. Idempotent: deleting a product that no longer exists returns 404, not an error state on your side.

The API key must own the product.

Args: api_key: Partle API key (prefix pk_). product_id: ID of the product to delete. Get from get_my_products.

Returns: {"deleted": product_id} on success.

Attach an image to an existing product. Provide exactly one of image_base64 (with content_type) or image_url.

Use this after create_product returns a product ID. For replacing a previously-uploaded image, delete the old one with delete_product_image first. Marked destructive because subsequent edits to the image set are visible publicly.

Args: api_key: Partle API key (prefix pk_). product_id: ID of the product to attach the image to. image_base64: Raw image data, base64-encoded. When set, content_type is required (e.g. image/jpeg). content_type: MIME type of the base64 payload. Required with image_base64. One of: image/jpeg, image/png, image/gif, image/webp. image_url: URL the server should fetch the image from. Use this when the image is already hosted somewhere public — saves base64 overhead.

Returns: The created ProductImage record with its id (use for deletion) and storage path.

Remove a specific image from a product. Destructive, idempotent.

Use when an image was uploaded by mistake or the merchant updated their listing. The product itself is preserved — only the image record and its file are removed. To remove the product entirely use delete_product.

Args: api_key: Partle API key (prefix pk_). product_id: ID of the product the image belongs to. image_id: ID of the image to delete. Visible in the images array of get_product responses.

Returns: {"deleted_image": image_id} on success.

List products created by the API key's owner. Requires an API key.

Use this when the user asks "what have I listed?" or before bulk operations like updating prices across multiple of their products. Distinct from search_products, which searches the public catalog without owner scoping.

Read-only.

Args: api_key: Partle API key (prefix pk_). limit: Maximum results (1–200, default 50).

Returns: {"result": [Product, …]} — same shape as search_products.

List the caller's personal inventory items. Requires an API key.

Use when the user asks "what do I own?", "what's on my wishlist?", "what am I selling?". Pass status to filter; default returns all.

Args: api_key: Partle API key, prefix pk_. Generate at https://partle.rubenayla.xyz/account. status: Lifecycle filter. One of: owned, wanted, for_sale, sold, discarded. Omit for all. product_id: Filter rows linked to a specific Partle product. project: Exact-match filter on project tag. q: Substring search on name + notes. limit: Page size 1–200, default 50. offset: Pagination offset.

Returns: {"items": [...], "count": int} — each item carries id, status, name (or linked product), quantity, prices, etc.

Add an item to the caller's personal inventory. Requires an API key.

One creation tool covers all lifecycle states — set status to match the user's intent: "I bought" → owned, "I want" → wanted, "I'm selling" → for_sale. Either product_id or name must be set. Not idempotent.

Args: api_key: Partle API key (prefix pk_). name: Freeform name for items not yet linked to a Partle product. product_id: Link to a canonical Partle product. status: Lifecycle. Default owned. quantity: How many. Fractional ok. 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 you paid. acquisition_currency: Currency of acquisition_price. purchased_at: ISO date (YYYY-MM-DD). asking_price: For status=for_sale. 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/.../line/1, content hash). Leave null for handwritten items. project: Tag for grouping.

Returns: The created inventory row.

Patch an inventory item. Only provided fields change. Idempotent.

Caller must own the item (404 otherwise — the API doesn't leak existence). For lifecycle changes, see mark_for_sale and mark_sold for ergonomic wrappers.

Permanently delete an inventory row. Caller must own it.

Args: api_key: Partle API key (prefix pk_). item_id: ID of the row to delete.

Returns: {"deleted": True, "id": item_id} on success.

Set status=for_sale and listing fields atomically.

Convenience wrapper for "list X for sale at Y€". Caller must own the item.

Mark an inventory item as sold (status=sold). Caller must own it.