{"openapi":"3.1.0","info":{"title":"MBNF Stock API","version":"1.0.0","description":"Live, read-only stock of MBNF SRL for B2B partners. Quantities are an offer, not a reservation: every order is confirmed by MBNF. Human-readable guide: https://mbnf.supply/api/docs\n\n**Sandbox:** the public key `mbnf_Sandbox1_public-test-key-sample-data-only` works on every endpoint and always returns the same sample products (never real stock), limited to 30 requests/minute and 1000/day per IP.","contact":{"name":"MBNF SRL","url":"https://mbnf.supply/api/docs#support"}},"servers":[{"url":"https://mbnf.supply/api/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Stock"},{"name":"Account"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your key, `mbnf_<id>_<secret>`. To try without one, use the sandbox key `mbnf_Sandbox1_public-test-key-sample-data-only`"}},"schemas":{"Size":{"type":"object","required":["size","quantity"],"properties":{"size":{"type":["string","null"],"description":"Size as printed on the box; null for one-size items"},"size_system":{"type":["string","null"],"enum":["US","US Men","US Women","US Youth","US Kids","EU","Apparel",null]},"size_eu":{"type":["string","null"],"description":"EU equivalent, when a conversion exists"},"quantity":{"type":"integer","minimum":1}},"example":{"size":"9","size_system":"US","size_eu":"42.5","quantity":3}},"Product":{"type":"object","required":["sku","name","total_quantity","sizes"],"properties":{"sku":{"type":"string","description":"Manufacturer style code, unique in the feed"},"name":{"type":"string"},"brand":{"type":["string","null"]},"image_url":{"type":["string","null"],"format":"uri"},"price":{"type":["integer","null"],"description":"Per pair, whole units of currency. Only present if prices are enabled for your account; null = no price yet"},"currency":{"type":"string","enum":["EUR"]},"price_vat_included":{"type":"boolean"},"total_quantity":{"type":"integer"},"sizes":{"type":"array","items":{"$ref":"#/components/schemas/Size"}}},"example":{"sku":"DD1391-100","name":"Nike Dunk Low Retro White Black","brand":"Nike","image_url":"https://image.goat.com/750/attachments/product_template_pictures/images/DD1391-100.png","price":145,"currency":"EUR","price_vat_included":false,"total_quantity":3,"sizes":[{"size":"9","size_system":"US","size_eu":"42.5","quantity":3}]}},"Meta":{"type":"object","properties":{"stock_updated_at":{"type":"string","format":"date-time"},"stale":{"type":"boolean","description":"True if the data is older than 24 hours"},"sandbox":{"type":"boolean","description":"Present (true) only with the sandbox key"}}},"PageMeta":{"allOf":[{"$ref":"#/components/schemas/Meta"},{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}]},"StockPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}},"StockItem":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"},"meta":{"$ref":"#/components/schemas/Meta"}}},"Me":{"type":"object","properties":{"client":{"type":"string"},"key_id":{"type":"string"},"key_expires":{"type":["string","null"],"format":"date"},"prices_included":{"type":"boolean"},"limits":{"type":"object","properties":{"requests_per_minute":{"type":"integer"},"requests_per_day":{"type":"integer"}}},"usage_today":{"type":"object","properties":{"requests":{"type":"integer"},"remaining":{"type":"integer"}}},"products":{"type":"integer"},"stock_updated_at":{"type":"string","format":"date-time"},"stale":{"type":"boolean"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["daily_quota_exceeded","internal_error","invalid_api_key","invalid_parameter","ip_not_allowed","key_in_query","method_not_allowed","not_found","rate_limited","server_busy","service_suspended","stock_unavailable","too_many_failed_attempts"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"paths":{"/stock":{"get":{"tags":["Stock"],"operationId":"listStock","summary":"List the products in stock","description":"Paginated, ordered by brand and name. A SKU or size missing from the feed is sold out.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}},{"name":"brand","in":"query","schema":{"type":"string","maxLength":60},"description":"Exact brand, case-insensitive"},{"name":"sku","in":"query","schema":{"type":"string","maxLength":60},"description":"Exact SKU, case-insensitive"},{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Search in SKU and name"},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"ETag of your last response"}],"responses":{"200":{"description":"Products","headers":{"RateLimit-Limit":{"description":"Requests per minute for your key","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests you can make right now","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-minute allowance is full again","schema":{"type":"integer"}},"X-Daily-Quota-Remaining":{"description":"Requests left today (UTC)","schema":{"type":"integer"}},"ETag":{"description":"Send it back as If-None-Match to get 304 when nothing changed","schema":{"type":"string"}},"X-Request-Id":{"description":"Quote it when contacting MBNF","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockPage"},"example":{"data":[{"sku":"DD1391-100","name":"Nike Dunk Low Retro White Black","brand":"Nike","image_url":"https://image.goat.com/750/attachments/product_template_pictures/images/DD1391-100.png","price":145,"currency":"EUR","price_vat_included":false,"total_quantity":3,"sizes":[{"size":"9","size_system":"US","size_eu":"42.5","quantity":3}]}],"meta":{"page":1,"per_page":100,"total":1,"total_pages":1,"stock_updated_at":"2026-10-14T09:12:00+00:00","stale":false}}}}},"304":{"description":"Not modified since your ETag (does not count against the daily quota)"},"400":{"description":"Invalid query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_parameter","message":"'per_page' must be an integer between 1 and 200.","request_id":"9f2c41d07e3a4b18"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"Missing or invalid API key. Send it as 'Authorization: Bearer <key>'.","request_id":"9f2c41d07e3a4b18"}}}},"403":{"description":"Key restricted to other IP addresses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ip_not_allowed","message":"This API key cannot be used from your IP address.","request_id":"9f2c41d07e3a4b18"}}}},"429":{"description":"Rate limited or daily quota exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Too many requests per minute. Retry after the number of seconds in 'Retry-After'.","request_id":"9f2c41d07e3a4b18"}}},"headers":{"Retry-After":{"description":"Seconds to wait","schema":{"type":"integer"}}}},"503":{"description":"Temporarily unavailable (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"stock_unavailable","message":"Stock data is not available yet. Retry in a few minutes.","request_id":"9f2c41d07e3a4b18"}}}}}}},"/stock/{sku}":{"get":{"tags":["Stock"],"operationId":"getProduct","summary":"One product by SKU","parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product","headers":{"RateLimit-Limit":{"description":"Requests per minute for your key","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests you can make right now","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the per-minute allowance is full again","schema":{"type":"integer"}},"X-Daily-Quota-Remaining":{"description":"Requests left today (UTC)","schema":{"type":"integer"}},"ETag":{"description":"Send it back as If-None-Match to get 304 when nothing changed","schema":{"type":"string"}},"X-Request-Id":{"description":"Quote it when contacting MBNF","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockItem"},"example":{"data":{"sku":"DD1391-100","name":"Nike Dunk Low Retro White Black","brand":"Nike","image_url":"https://image.goat.com/750/attachments/product_template_pictures/images/DD1391-100.png","price":145,"currency":"EUR","price_vat_included":false,"total_quantity":3,"sizes":[{"size":"9","size_system":"US","size_eu":"42.5","quantity":3}]},"meta":{"stock_updated_at":"2026-10-14T09:12:00+00:00","stale":false}}}}},"404":{"description":"Not available for you right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found","message":"This SKU is not in your catalog (or it is out of stock).","request_id":"9f2c41d07e3a4b18"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"Missing or invalid API key. Send it as 'Authorization: Bearer <key>'.","request_id":"9f2c41d07e3a4b18"}}}},"403":{"description":"Key restricted to other IP addresses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ip_not_allowed","message":"This API key cannot be used from your IP address.","request_id":"9f2c41d07e3a4b18"}}}},"429":{"description":"Rate limited or daily quota exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Too many requests per minute. Retry after the number of seconds in 'Retry-After'.","request_id":"9f2c41d07e3a4b18"}}},"headers":{"Retry-After":{"description":"Seconds to wait","schema":{"type":"integer"}}}},"503":{"description":"Temporarily unavailable (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"stock_unavailable","message":"Stock data is not available yet. Retry in a few minutes.","request_id":"9f2c41d07e3a4b18"}}}}}}},"/me":{"get":{"tags":["Account"],"operationId":"getMe","summary":"Your key, limits and usage today","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"Missing or invalid API key. Send it as 'Authorization: Bearer <key>'.","request_id":"9f2c41d07e3a4b18"}}}},"403":{"description":"Key restricted to other IP addresses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"ip_not_allowed","message":"This API key cannot be used from your IP address.","request_id":"9f2c41d07e3a4b18"}}}},"429":{"description":"Rate limited or daily quota exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited","message":"Too many requests per minute. Retry after the number of seconds in 'Retry-After'.","request_id":"9f2c41d07e3a4b18"}}},"headers":{"Retry-After":{"description":"Seconds to wait","schema":{"type":"integer"}}}},"503":{"description":"Temporarily unavailable (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"stock_unavailable","message":"Stock data is not available yet. Retry in a few minutes.","request_id":"9f2c41d07e3a4b18"}}}}}}}}}