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_xxxxxxxxxxxxxxxxxxxx

Requests 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-api

Rate 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

GET/listings

List your own listings. Query params: itemType, status, condition, q, sort, page, size.

POST/listings

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"
  }'
PUT/listings/{id}

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/listings/{id}

Delete a listing.

POST/listings/bulk

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" }
]
POST/listings/bulk-update

Update price/quantity/status for up to 100 listings in one request.

[
  { "listingId": "7b3e...", "price": 1150, "quantity": 1 },
  { "listingId": "9f2a...", "status": "removed" }
]
GET/availability

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}.

FieldTypeRequiredDescription
idUUID—Unique listing identifier.
sellerIdUUID—Owner of the listing (you).
itemTypestring—One of: set, minifig, element, part, custom.
itemIdstring—Catalog identifier of the item.
itemNamestring—Resolved catalog name of the item.
conditionstring—new or used.
pricenumber—Price in the listing currency.
currencystring—UAH, USD, or EUR.
quantityinteger—Available quantity.
statusstring—active, sold, reserved, removed, pending_approval, or rejected.
commentstring—Public, buyer-facing note.
remarksstring—Private seller note (only on your own listings).
detailsobject—Type-specific flags (e.g. set completeness, minifig accessories).
primaryImageUrlstring—URL of the primary image.
imagesarray—Image entries: { id, url, displayOrder }.
featuredboolean—Featured flag (PRO sellers only).
soldAttimestamp—When the listing was sold (nullable).
createdAttimestamp—Creation time.
updatedAttimestamp—Last update time.
rejectionReasonstring—Reason, set when status is rejected.

CreateListingRequest

Request body for POST /listings (and items of POST /listings/bulk).

FieldTypeRequiredDescription
itemTypestringyesset, minifig, element, or custom.
itemIdstring—Catalog id (for set / minifig / custom).
partIdstring—Part number (for element; pair with colorName).
colorNamestring—Color name used to resolve an element.
conditionstringyesnew or used.
pricenumberyesMust be greater than 0.
currencystringyesUAH, USD, or EUR.
quantityintegeryesMust be at least 1.
commentstring—Public, buyer-facing note.
remarksstring—Private seller note.
detailsobject—Type-specific flags.

UpdateListingRequest

Request body for PUT /listings/{id}. Omitted/null fields are left unchanged.

FieldTypeRequiredDescription
pricenumber—New price; must be greater than 0.
quantityinteger—New quantity; 0 or more.
statusstring—New status, e.g. removed.
commentstring—Public note.
remarksstring—Private note.
detailsobject—Type-specific flags.

BulkUpdateItem

Array element for POST /listings/bulk-update.

FieldTypeRequiredDescription
listingIdUUIDyesThe listing to update.
pricenumber—New price (optional).
quantityinteger—New quantity (optional).
statusstring—New status (optional).

BulkResultItem

Response element for bulk operations (bulk / bulk-update).

FieldTypeRequiredDescription
indexinteger—Position of the item in the submitted array.
okboolean—Whether this item succeeded.
listingIdUUID | null—Resulting/target listing id (null on failure to create).
errorstring | null—Error message when ok is false.

AvailabilityResponse

Response of GET /availability. Prices are converted to UAH.

FieldTypeRequiredDescription
itemTypestring—Echoes the requested item type.
itemIdstring—Echoes the requested item id.
availableboolean—True if at least one active offer exists.
totalOffersinteger—Total active offers across sellers.
pageinteger—Current page (0-indexed).
sizeinteger—Page size.
totalPagesinteger—Total number of pages.
offersOffer[]—Offers on this page (see below).

Offer

One entry in AvailabilityResponse.offers. Other sellers’ private fields are never exposed.

FieldTypeRequiredDescription
listingIdUUID—Identifier of the offer listing.
sellerIdUUID—Seller offering the item.
conditionstring—new or used.
pricenumber—Price converted to UAH.
currencystring—Always UAH for availability.
quantityinteger—Available quantity.
commentstring—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.