Build on MINTSHUB

Overview

Every API key is bound to one MINTSHUB account. A client receives only that account's export items—never the private catalog or another owner's data.

Authentication

Send the key in the X-API-Key header. Keys are issued by a MINTSHUB administrator and shown only once.

curl -H "X-API-Key: $MINTSHUB_API_KEY" "https://api.mintshub.com/v1/export/items?lang=ENG"

Export items

Export items are ready listings enriched by MINTSHUB on the server.

Query parameters

Core item fields

Synchronization pattern

Shop schema

The sale module reads a PrestaShop shop so its categories, features and shared feature values can be matched to mintsHUB. This route does not use a MINTSHUB API key. The shop webservice key is used for that request only and is not stored.

External sales

A platform can notify MINTSHUB after a confirmed purchase. MINTSHUB marks the item inactive and exposes stock 0 to every export consumer.

curl -X POST   -H "X-API-Key: $MINTSHUB_SALES_API_KEY"   -H "Idempotency-Key: confirm-order-12345"   -H "Content-Type: application/json"   -d '{"external_order_id":"12345","quantity":1}'   "https://api.mintshub.com/v1/export/items/9762/sales/confirm"

curl -X POST   -H "X-API-Key: $MINTSHUB_SALES_API_KEY"   -H "Idempotency-Key: cancel-order-12345"   -H "Content-Type: application/json"   -d '{"external_order_id":"12345","quantity":1}'   "https://api.mintshub.com/v1/export/items/9762/sales/cancel"

Use a stable, unique Idempotency-Key for each operation. Retry the identical request with the same key. Use a new key for cancellation.

Errors

Every error contains error.code, error.message and meta.request_id.

Examples

JavaScript — incremental page

const url = new URL("https://api.mintshub.com/v1/export/items");
url.searchParams.set("lang", "ENG");
url.searchParams.set("limit", "100");
url.searchParams.set("updated_after", lastSuccessfulSync);

const response = await fetch(url, {
  headers: { "X-API-Key": process.env.MINTSHUB_API_KEY }
});
if (!response.ok) throw new Error(`MINTSHUB HTTP ${response.status}`);
const { data, meta } = await response.json();

Python — one item

import os
import requests

response = requests.get(
    "https://api.mintshub.com/v1/export/items/9762",
    headers={"X-API-Key": os.environ["MINTSHUB_API_KEY"]},
    params={"lang": "ENG"},
    timeout=15,
)
response.raise_for_status()
item = response.json()["data"]

Changes

Only contract changes that affect integrators. Internal refactors and server-only edits are not listed.

1.3.1 — 2026-10-15

The sale module can match a shop's shared feature values to mintsHUB lists such as metal, condition and certification. Those values already exist in the shop and now come back with the schema.

Added

• `POST /sync/prestashop/schema`: each item in `data.features` includes `values`, a list of `{id, name}` shared values for that feature. Up to 5000 values.

This log records only contract changes that affect integrators: routes, parameters, response fields, authentication, errors and documented behaviour. Internal refactors, server tuning, tests and cosmetic edits are omitted.

1.3.0 — 2026-10-11

The sale module can ask this server to read a PrestaShop shop's categories and features. The shop webservice key is used only for that request and is not stored.

Added

• `POST /sync/prestashop/schema` with `base_url` and `ws_key`. No MINTSHUB API key. Response `data.categories` and `data.features`.
• Errors: `invalid_base_url`, `base_url_must_be_https`, `base_url_not_allowed`, `missing_ws_key`, `prestashop_401`, `prestashop_403`.

1.2.0 — 2026-09-21

Public owner-scoped export API for marketplaces, AI agents and custom sites. A key never sees another owner's catalog or MINTSHUB internals.

Added

• `GET /export/items` and `GET /export/items/{item_id}` for ready listings (`export:read`).
• Incremental sync with `updated_after` and opaque `meta.next_cursor`.
• `POST /export/items/{item_id}/sales/confirm` and `/sales/cancel` with `Idempotency-Key` (`sales:write`, one platform per key).
• Content languages `ENG`, `RUS`, `UKR`.
• Uniform errors: `error.code`, `error.message`, `meta.request_id`.

Why

Integrators needed a stable HTTPS JSON contract that does not depend on PrestaShop and does not expose the private MINTSHUB catalog.

Security requirements

• Use HTTPS and keep keys in a secret manager or protected environment file.
• Use separate read and write keys to minimize impact if one integration is compromised.
• Never accept an owner ID or platform ID from an untrusted client; both are bound to the key by MINTSHUB.
• Log meta.request_id, not API keys or full authorization headers.
• Rotate and revoke a key immediately if it is exposed.