Developer API
A public REST API to manage your inventory and prices, run bulk operations, and check item availability across the marketplace.
Use with AI agents (MCP)
This API is available as an MCP server for Claude Desktop/Code and other MCP clients — manage your inventory and prices straight from an AI agent using your token. Run it locally via npx @brickmart/mcp.
Authentication
Generate a personal token on your profile settings page. The token is shown only once — store it safely. Send it in the header of every request:
Authorization: Bearer bm_live_xxxxxxxxxxxxxxxxxxxxRequests are authenticated as you — all write operations act on your own inventory. Revoke a token at any time from your profile page.
Base URL
https://brickmart.shop/public-apiRate limits
Roughly 120 requests per minute per token; bulk operations are limited more strictly (about 10/min). When exhausted, the API returns 429 with X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After.
Endpoints
List your own listings. Query params: itemType, status, condition, q, sort, page, size.
Create a listing.
curl -X POST https://brickmart.shop/public-api/listings \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"itemType": "set",
"itemId": "75060-1",
"condition": "new",
"price": 1299.00,
"currency": "UAH",
"quantity": 2,
"comment": "Sealed box"
}'Update price, quantity, status, or comment. All fields optional.
curl -X PUT https://brickmart.shop/public-api/listings/$ID \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "price": 1150.00, "quantity": 1 }'Delete a listing.
Create up to 100 listings in one request. Returns a per-item result.
[
{ "itemType": "set", "itemId": "75060-1", "condition": "new", "price": 1299, "currency": "UAH", "quantity": 2 },
{ "itemType": "minifig", "itemId": "sw0547", "condition": "used", "price": 150, "currency": "UAH", "quantity": 1 }
]
// response
[
{ "index": 0, "ok": true, "listingId": "7b3e...", "error": null },
{ "index": 1, "ok": false, "listingId": null, "error": "Item not found in catalog" }
]Update price/quantity/status for up to 100 listings in one request.
[
{ "listingId": "7b3e...", "price": 1150, "quantity": 1 },
{ "listingId": "9f2a...", "status": "removed" }
]Availability of an item across all marketplace sellers. Params: itemType, itemId, page, size. Prices are converted to UAH.
GET /public-api/availability?itemType=set&itemId=75060-1
{
"itemType": "set",
"itemId": "75060-1",
"available": true,
"totalOffers": 4,
"page": 0, "size": 20, "totalPages": 1,
"offers": [
{ "listingId": "7b3e...", "sellerId": "a1c2...", "condition": "new", "price": 1299, "currency": "UAH", "quantity": 2, "comment": "Sealed box" }
]
}Schema
Field-level reference for request and response objects. Identifiers are UUIDs, monetary amounts are decimals, and timestamps are ISO-8601 (UTC).
Listing
Returned by GET /listings, POST /listings, and PUT /listings/{id}.
| Field | Type | Required | Description |
|---|---|---|---|
| id | UUID | — | Unique listing identifier. |
| sellerId | UUID | — | Owner of the listing (you). |
| itemType | string | — | One of: set, minifig, element, part, custom. |
| itemId | string | — | Catalog identifier of the item. |
| itemName | string | — | Resolved catalog name of the item. |
| condition | string | — | new or used. |
| price | number | — | Price in the listing currency. |
| currency | string | — | UAH, USD, or EUR. |
| quantity | integer | — | Available quantity. |
| status | string | — | active, sold, reserved, removed, pending_approval, or rejected. |
| comment | string | — | Public, buyer-facing note. |
| remarks | string | — | Private seller note (only on your own listings). |
| details | object | — | Type-specific flags (e.g. set completeness, minifig accessories). |
| primaryImageUrl | string | — | URL of the primary image. |
| images | array | — | Image entries: { id, url, displayOrder }. |
| featured | boolean | — | Featured flag (PRO sellers only). |
| soldAt | timestamp | — | When the listing was sold (nullable). |
| createdAt | timestamp | — | Creation time. |
| updatedAt | timestamp | — | Last update time. |
| rejectionReason | string | — | Reason, set when status is rejected. |
CreateListingRequest
Request body for POST /listings (and items of POST /listings/bulk).
| Field | Type | Required | Description |
|---|---|---|---|
| itemType | string | yes | set, minifig, element, or custom. |
| itemId | string | — | Catalog id (for set / minifig / custom). |
| partId | string | — | Part number (for element; pair with colorName). |
| colorName | string | — | Color name used to resolve an element. |
| condition | string | yes | new or used. |
| price | number | yes | Must be greater than 0. |
| currency | string | yes | UAH, USD, or EUR. |
| quantity | integer | yes | Must be at least 1. |
| comment | string | — | Public, buyer-facing note. |
| remarks | string | — | Private seller note. |
| details | object | — | Type-specific flags. |
UpdateListingRequest
Request body for PUT /listings/{id}. Omitted/null fields are left unchanged.
| Field | Type | Required | Description |
|---|---|---|---|
| price | number | — | New price; must be greater than 0. |
| quantity | integer | — | New quantity; 0 or more. |
| status | string | — | New status, e.g. removed. |
| comment | string | — | Public note. |
| remarks | string | — | Private note. |
| details | object | — | Type-specific flags. |
BulkUpdateItem
Array element for POST /listings/bulk-update.
| Field | Type | Required | Description |
|---|---|---|---|
| listingId | UUID | yes | The listing to update. |
| price | number | — | New price (optional). |
| quantity | integer | — | New quantity (optional). |
| status | string | — | New status (optional). |
BulkResultItem
Response element for bulk operations (bulk / bulk-update).
| Field | Type | Required | Description |
|---|---|---|---|
| index | integer | — | Position of the item in the submitted array. |
| ok | boolean | — | Whether this item succeeded. |
| listingId | UUID | null | — | Resulting/target listing id (null on failure to create). |
| error | string | null | — | Error message when ok is false. |
AvailabilityResponse
Response of GET /availability. Prices are converted to UAH.
| Field | Type | Required | Description |
|---|---|---|---|
| itemType | string | — | Echoes the requested item type. |
| itemId | string | — | Echoes the requested item id. |
| available | boolean | — | True if at least one active offer exists. |
| totalOffers | integer | — | Total active offers across sellers. |
| page | integer | — | Current page (0-indexed). |
| size | integer | — | Page size. |
| totalPages | integer | — | Total number of pages. |
| offers | Offer[] | — | Offers on this page (see below). |
Offer
One entry in AvailabilityResponse.offers. Other sellers’ private fields are never exposed.
| Field | Type | Required | Description |
|---|---|---|---|
| listingId | UUID | — | Identifier of the offer listing. |
| sellerId | UUID | — | Seller offering the item. |
| condition | string | — | new or used. |
| price | number | — | Price converted to UAH. |
| currency | string | — | Always UAH for availability. |
| quantity | integer | — | Available quantity. |
| comment | string | — | Public, buyer-facing note. |
Errors
Errors use standard HTTP status codes with a JSON body:
{ "error": "Rate limit exceeded" }401 — missing/invalid token · 400 — bad request · 404 — not found · 422 — listing limit exceeded · 429 — rate limit exceeded.
