{ "openapi": "3.1.0", "info": { "title": "Pure Public API", "description": "Public API for accessing Pure marketplace data including products, spot prices, and more.", "version": "2.0.0", "license": { "name": "Proprietary" } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "name": "x-api-key", "in": "header", "description": "API key for authentication" } }, "schemas": {} }, "paths": { "/": { "get": { "summary": "API Information", "tags": [ "Root" ], "description": "Get information about the API and available endpoints", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "documentation": { "type": "string" }, "endpoints": { "type": "object", "properties": { "swagger": { "type": "string" }, "health": { "type": "string" } }, "required": [ "swagger", "health" ], "additionalProperties": false } }, "required": [ "name", "version", "description", "endpoints" ], "additionalProperties": false } } } } } } }, "/products/get-product-analytics/v1": { "get": { "summary": "Get product analytics", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product analytics\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "productId", "required": true, "description": "The ID of the product to get analytics for" }, { "schema": { "type": "string" }, "in": "query", "name": "variantId", "required": true, "description": "The ID of the variant to get analytics for" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "range", "required": true, "description": "The range of days to get analytics for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "marketPrice": { "type": "object", "properties": { "value": { "type": "number" }, "change": { "type": "number" }, "changePercent": { "type": "number" }, "dataPoints": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "timestamp": { "type": "string" } }, "required": [ "value", "timestamp" ], "additionalProperties": false } } }, "required": [ "value", "change", "changePercent", "dataPoints" ], "additionalProperties": false }, "premium": { "type": "object", "properties": { "value": { "type": "number" }, "change": { "type": "number" }, "changePercent": { "type": "number" }, "dataPoints": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "timestamp": { "type": "string" } }, "required": [ "value", "timestamp" ], "additionalProperties": false } } }, "required": [ "value", "change", "changePercent", "dataPoints" ], "additionalProperties": false }, "depth": { "type": "object", "properties": { "value": { "type": "number" }, "change": { "type": "number" }, "changePercent": { "type": "number" }, "dataPoints": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "timestamp": { "type": "string" } }, "required": [ "value", "timestamp" ], "additionalProperties": false } } }, "required": [ "value", "change", "changePercent", "dataPoints" ], "additionalProperties": false } }, "required": [ "marketPrice", "premium", "depth" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-activity/v1": { "get": { "summary": "Get product activity", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product activity\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "productId", "required": true, "description": "The ID of the product to get activity for" }, { "schema": { "type": "string" }, "in": "query", "name": "variantId", "required": true, "description": "The ID of the variant to get activity for" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "createdAt": { "type": "string" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "event", "createdAt", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-order-book/v1": { "get": { "summary": "Get product order book", "tags": [ "Products (Legacy)" ], "description": "Retrieve the order book for a product\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": true }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "variantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "isUsersOrder": { "type": "boolean" }, "usersQty": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar", "isUsersOrder", "usersQty" ], "additionalProperties": false } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "isUsersOrder": { "type": "boolean" }, "usersQty": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar", "isUsersOrder", "usersQty" ], "additionalProperties": false } } }, "required": [ "listings", "offers" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/v2/{id}/orderbook": { "get": { "summary": "Get live orderbook for a product", "tags": [ "Products" ], "description": "Retrieve the live orderbook for a product across all variants. Returns active listings and offers from the `orderbook_listing_live` and `orderbook_offer_live` views (already filtered to active, non-expired, trading-enabled organizations).\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantTitle": { "type": "string" }, "listings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumPercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "premiumPercent", "premiumDollar", "type", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumPercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "premiumPercent", "premiumDollar", "type", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "variantId", "variantTitle", "listings", "offers" ], "additionalProperties": false } } }, "required": [ "productId", "variants" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/v3/{id}": { "get": { "summary": "Get enriched product details", "tags": [ "Products" ], "description": "Retrieve a single product with all variants (including best offer/listing and order book per variant) and recent activity.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "purity": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "sku": { "type": "string" }, "isCertified": { "type": "boolean" }, "isIra": { "type": "boolean" }, "material": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "manufacturer": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "isEsg": { "type": "boolean" } }, "required": [ "title", "images", "isEsg" ], "additionalProperties": false }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "isNumismatic": { "type": "boolean" } }, "required": [ "title", "isNumismatic" ], "additionalProperties": false }, { "type": "null" } ] }, "subCategory": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "premiumCalculationType": { "type": "string" } }, "required": [ "title", "premiumCalculationType" ], "additionalProperties": false }, { "type": "null" } ] }, "certificateProvider": { "anyOf": [ { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highestOffer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "lowestListing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "orderBook": { "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } }, "offers": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "qty": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "price", "qty", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } } }, "required": [ "listings", "offers" ], "additionalProperties": false } }, "required": [ "id", "title", "highestOffer", "lowestListing", "images", "orderBook" ], "additionalProperties": false } }, "recentActivity": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "createdAt": { "type": "string" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" } }, "required": [ "event", "createdAt", "price", "quantity", "spotPremium", "spotPremiumDollar" ], "additionalProperties": false } } }, "required": [ "id", "title", "purity", "weight", "weightGrams", "sku", "isCertified", "isIra", "material", "attributes", "images", "manufacturer", "category", "subCategory", "certificateProvider", "variants", "recentActivity" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/v1/catalog": { "get": { "summary": "Get product catalog metadata", "tags": [ "Products" ], "description": "Retrieve all product catalog metadata in a single request — categories, subcategories, manufacturers, materials, attributes, and certificate providers.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "isNumismatic": { "type": "boolean" }, "allowCardPayments": { "type": "boolean" }, "isInstantShip": { "type": "boolean" } }, "required": [ "id", "title", "description", "createdAt", "isNumismatic", "allowCardPayments", "isInstantShip" ], "additionalProperties": false } }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumCalculationType": { "type": "string", "enum": [ "unit", "troy_ounce" ] }, "feeRate": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "advancedFeeRate": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] } }, "required": [ "id", "createdAt", "title", "description", "premiumCalculationType", "feeRate", "advancedFeeRate" ], "additionalProperties": false } }, "manufacturers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "isEsg": { "type": "boolean" } }, "required": [ "id", "title", "description", "updatedAt", "createdAt", "images", "isEsg" ], "additionalProperties": false } }, "materials": { "type": "array", "items": { "type": "string" } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "type", "title", "description" ], "additionalProperties": false } }, "certificateProviders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "createdAt", "description", "title" ], "additionalProperties": false } } }, "required": [ "categories", "subcategories", "manufacturers", "materials", "attributes", "certificateProviders" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/v1/search": { "get": { "summary": "Search products", "tags": [ "Products" ], "description": "Search and browse products with full-text search, filtering, and facets. Returns enriched product data with variants hydrated from the database.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Search query. Omit or pass '*' to browse all products." }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 250 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of products to return (default 10, max 250)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of products to skip for pagination" }, { "schema": { "type": "string" }, "in": "query", "name": "filter_by", "required": false, "description": "Typesense filter expression (e.g. 'material:=Gold && has_listing:=true')" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "category": { "type": "string" }, "subCategory": { "type": "string" }, "material": { "type": "string" }, "manufacturer": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "purity": { "type": "string" }, "premiumCalculationType": { "type": "string" }, "certificateProvider": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "number" } }, "images": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sortKey": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "listing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "price": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" } }, "required": [ "id", "price", "spotPremium", "spotPremiumDollar", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ] }, "offer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "price": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" } }, "required": [ "id", "price", "spotPremium", "spotPremiumDollar", "expiresAt" ], "additionalProperties": false }, { "type": "null" } ] }, "flags": { "type": "object", "properties": { "isStockedByBbStore": { "type": "boolean" }, "isCertified": { "type": "boolean" }, "isEsg": { "type": "boolean" }, "isIra": { "type": "boolean" }, "isNumismatic": { "type": "boolean" }, "hasListing": { "type": "boolean" }, "hasOffer": { "type": "boolean" } }, "additionalProperties": false }, "viewCount": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "description", "sku", "category", "subCategory", "material", "manufacturer", "weight", "weightGrams", "purity", "premiumCalculationType", "viewCount" ], "additionalProperties": false } }, "total": { "type": "number" }, "facets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "sum": { "type": "number" }, "avg": { "type": "number" }, "totalValues": { "type": "number" } }, "additionalProperties": false } }, "required": [ "field", "counts" ], "additionalProperties": false } } }, "required": [ "products", "total" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/search-products/v2": { "get": { "summary": "Search products", "tags": [ "Products (Legacy)" ], "description": "Search for products. When no query is provided, returns all products with pagination.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "query", "required": true, "description": "Search query string" }, { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "in": "query", "name": "pagination", "required": false, "description": "Pagination parameters (limit and offset)" }, { "schema": { "type": "string" }, "in": "query", "name": "filter_by", "required": false, "description": "Typesense filter expression (e.g. 'material:=Gold && has_listing:=true')" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "found": { "type": "number" }, "hits": { "type": "array", "items": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "category": { "type": "string" }, "sub_category": { "type": "string" }, "material": { "type": "string" }, "manufacturer": { "type": "string" }, "weight": { "type": "string" }, "weight_grams": { "type": "number" }, "purity": { "type": "string" }, "premium_calculation_type": { "type": "string" }, "certificate_provider": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "number" } }, "variants": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "listing_id": { "type": "string" }, "listing_price": { "type": "number" }, "listing_spot_premium": { "type": "number" }, "listing_spot_premium_dollar": { "type": "number" }, "listing_expires_at": { "type": "string" }, "offer_id": { "type": "string" }, "offer_price": { "type": "number" }, "offer_spot_premium": { "type": "number" }, "offer_spot_premium_dollar": { "type": "number" }, "offer_expires_at": { "type": "string" }, "is_stocked_by_bb_store": { "type": "boolean" }, "is_certified": { "type": "boolean" }, "is_esg": { "type": "boolean" }, "is_ira": { "type": "boolean" }, "is_numismatic": { "type": "boolean" }, "has_listing": { "type": "boolean" }, "has_offer": { "type": "boolean" }, "favorite_count": { "type": "number" }, "view_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "description", "sku", "category", "sub_category", "material", "manufacturer", "weight", "weight_grams", "purity", "premium_calculation_type", "view_count" ], "additionalProperties": false }, "highlights": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "snippet": { "type": "string" }, "matched_tokens": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } ] } }, "required": [ "field", "matched_tokens" ], "additionalProperties": false } }, "text_match": { "type": "number" }, "text_match_info": { "type": "object", "properties": { "best_field_score": { "type": "string" }, "best_field_weight": { "type": "number" }, "fields_matched": { "type": "number" }, "score": { "type": "string" }, "tokens_matched": { "type": "number" } }, "additionalProperties": false } }, "required": [ "document" ], "additionalProperties": false } }, "facet_counts": { "type": "array", "items": { "type": "object", "properties": { "field_name": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" }, "highlighted": { "type": "string" } }, "required": [ "value", "count" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "sum": { "type": "number" }, "avg": { "type": "number" }, "total_values": { "type": "number" } }, "additionalProperties": false } }, "required": [ "field_name", "counts" ], "additionalProperties": false } }, "page": { "type": "number" }, "out_of": { "type": "number" }, "search_time_ms": { "type": "number" }, "request_params": { "type": "object", "properties": { "collection_name": { "type": "string" }, "per_page": { "type": "number" }, "q": { "type": "string" } }, "additionalProperties": false } }, "required": [ "found" ], "additionalProperties": false } } } } } } }, "/products/search-products/v3": { "get": { "summary": "Search products", "tags": [ "Products (Legacy)" ], "description": "Search for products. When no query is provided, returns all products with pagination.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "query", "required": false, "description": "Search query. Omit or pass '*' to browse all products." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 250 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of products to return (default 10, max 250)" }, { "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of products to skip for pagination" }, { "schema": { "type": "string" }, "in": "query", "name": "filter_by", "required": false, "description": "Typesense filter expression (e.g. 'material:=Gold && has_listing:=true')" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "category": { "type": "string" }, "sub_category": { "type": "string" }, "material": { "type": "string" }, "manufacturer": { "type": "string" }, "weight": { "type": "string" }, "weight_grams": { "type": "number" }, "purity": { "type": "string" }, "premium_calculation_type": { "type": "string" }, "certificate_provider": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "number" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sortKey": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "images": { "type": "array", "items": { "type": "string" } }, "listing_id": { "type": "string" }, "listing_price": { "type": "number" }, "listing_spot_premium": { "type": "number" }, "listing_spot_premium_dollar": { "type": "number" }, "listing_expires_at": { "type": "string" }, "offer_id": { "type": "string" }, "offer_price": { "type": "number" }, "offer_spot_premium": { "type": "number" }, "offer_spot_premium_dollar": { "type": "number" }, "offer_expires_at": { "type": "string" }, "is_stocked_by_bb_store": { "type": "boolean" }, "is_certified": { "type": "boolean" }, "is_esg": { "type": "boolean" }, "is_ira": { "type": "boolean" }, "is_numismatic": { "type": "boolean" }, "has_listing": { "type": "boolean" }, "has_offer": { "type": "boolean" }, "favorite_count": { "type": "number" }, "view_count": { "type": "number" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "description", "sku", "category", "sub_category", "material", "manufacturer", "weight", "weight_grams", "purity", "premium_calculation_type", "view_count" ], "additionalProperties": false } }, "total": { "type": "number" }, "facets": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ], "additionalProperties": false } }, "stats": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" }, "sum": { "type": "number" }, "avg": { "type": "number" }, "total_values": { "type": "number" } }, "additionalProperties": false } }, "required": [ "field", "counts" ], "additionalProperties": false } } }, "required": [ "products", "total" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-options/v1": { "get": { "summary": "Get product options", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product options with images, categories, and variants\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "value", "label", "variants" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-certificate-providers/v1": { "get": { "summary": "Get certificate providers", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product certificate providers\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "createdAt", "description", "title" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-attributes/v1": { "get": { "summary": "Get product attributes", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product attributes\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "type": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "type", "title", "description" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-materials/v1": { "get": { "summary": "Get product materials", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product materials\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string", "enum": [ "Gold", "Silver", "Platinum", "Palladium", "Bitcoin" ] } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-products/v1": { "get": { "summary": "Get products by IDs", "tags": [ "Products (Legacy)" ], "description": "Retrieve products by their IDs with variants, offers, and listings\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "ids", "required": true, "description": "Comma separated list of product IDs to retrieve" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "purity": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "sku": { "type": "string" }, "isCertified": { "type": "boolean" }, "isIra": { "type": "boolean" }, "material": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "manufacturer": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "isEsg": { "type": "boolean" } }, "required": [ "title", "images", "isEsg" ], "additionalProperties": false }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "isNumismatic": { "type": "boolean" } }, "required": [ "title", "isNumismatic" ], "additionalProperties": false }, { "type": "null" } ] }, "subCategory": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "premiumCalculationType": { "type": "string" } }, "required": [ "title", "premiumCalculationType" ], "additionalProperties": false }, { "type": "null" } ] }, "certificateProvider": { "anyOf": [ { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highestOffer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "lowestListing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "title", "highestOffer", "lowestListing", "images" ], "additionalProperties": false } } }, "required": [ "id", "title", "purity", "weight", "weightGrams", "sku", "isCertified", "isIra", "material", "attributes", "images", "manufacturer", "category", "subCategory", "certificateProvider", "variants" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-products/v2": { "get": { "summary": "Get products with filtering", "tags": [ "Products (Legacy)" ], "description": "Retrieve products filtered by material and attributes, with variants, offers, and listings. Returns paginated results.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "material", "required": false, "description": "Filter by material (Gold, Silver, Platinum, Palladium, Bitcoin)" }, { "schema": { "type": "string" }, "in": "query", "name": "attributeIds", "required": false, "description": "Comma separated attribute IDs (AND semantics)" }, { "schema": { "default": 10, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of products to return (default 10, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of products to skip for pagination" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "purity": { "type": "string" }, "weight": { "type": "string" }, "weightGrams": { "type": "number" }, "sku": { "type": "string" }, "isCertified": { "type": "boolean" }, "isIra": { "type": "boolean" }, "material": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "string" } }, "manufacturer": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "isEsg": { "type": "boolean" } }, "required": [ "title", "images", "isEsg" ], "additionalProperties": false }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "isNumismatic": { "type": "boolean" } }, "required": [ "title", "isNumismatic" ], "additionalProperties": false }, { "type": "null" } ] }, "subCategory": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "premiumCalculationType": { "type": "string" } }, "required": [ "title", "premiumCalculationType" ], "additionalProperties": false }, { "type": "null" } ] }, "certificateProvider": { "anyOf": [ { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title" ], "additionalProperties": false }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highestOffer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "lowestListing": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "type": "number" }, "quantity": { "type": "number" }, "spotPremium": { "type": "number" }, "spotPremiumDollar": { "type": "number" }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "spotPremium", "spotPremiumDollar", "expiresAt", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "title", "highestOffer", "lowestListing", "images" ], "additionalProperties": false } } }, "required": [ "id", "title", "purity", "weight", "weightGrams", "sku", "isCertified", "isIra", "material", "attributes", "images", "manufacturer", "category", "subCategory", "certificateProvider", "variants" ], "additionalProperties": false } }, "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } }, "required": [ "data", "total", "limit", "offset" ], "additionalProperties": false } } } } } } }, "/products/get-product-categories/v1": { "get": { "summary": "Get product categories", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product categories\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "isNumismatic": { "type": "boolean" }, "allowCardPayments": { "type": "boolean" }, "isInstantShip": { "type": "boolean" } }, "required": [ "id", "title", "description", "createdAt", "isNumismatic", "allowCardPayments", "isInstantShip" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-subcategories/v1": { "get": { "summary": "Get product subcategories", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product subcategories\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumCalculationType": { "type": "string", "enum": [ "unit", "troy_ounce" ] }, "feeRate": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "advancedFeeRate": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] } }, "required": [ "id", "createdAt", "title", "description", "premiumCalculationType", "feeRate", "advancedFeeRate" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/products/get-product-manufacturers/v1": { "get": { "summary": "Get product manufacturers", "tags": [ "Products (Legacy)" ], "description": "Retrieve all product manufacturers\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "images": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "isEsg": { "type": "boolean" } }, "required": [ "id", "title", "description", "updatedAt", "createdAt", "images", "isEsg" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-spot-price/v1": { "get": { "summary": "Get spot price", "tags": [ "Marketplace" ], "description": "Retrieve current spot prices for all precious metals. This endpoint returns the current bid/ask prices, market status, and price changes for all supported materials.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "material": { "type": "string", "enum": [ "Gold", "Silver", "Platinum", "Palladium", "Bitcoin" ] }, "bid": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ask": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "changePositive": { "type": "boolean" }, "changePrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "material", "bid", "ask", "changePositive", "changePrice" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-recommended-shipping-date/v1": { "get": { "summary": "Get recommended shipping date", "tags": [ "Marketplace" ], "description": "Retrieve the recommended shipping date for the product. This endpoint returns the two day and overnight shipping dates.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "twoDayLabel": { "type": "string", "format": "date-time" }, "overnightLabel": { "type": "string", "format": "date-time" } }, "required": [ "twoDayLabel", "overnightLabel" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-sitemap-products/v1": { "get": { "summary": "Get sitemap products", "tags": [ "Marketplace" ], "description": "Retrieve all products for the sitemap. This endpoint returns the sku and updatedAt for all products.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "sku", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/marketplace/get-marketplace-stats/v1": { "get": { "summary": "Get platform-wide marketplace statistics", "tags": [ "Marketplace" ], "description": "Retrieve aggregate marketplace statistics including total ask/bid amounts, listing/offer counts, and product counts. Stats are recalculated every minute.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalAskAmount": { "type": "number", "description": "Total value of all active listings in cents" }, "totalBidAmount": { "type": "number", "description": "Total value of all active offers in cents" }, "totalListingCount": { "type": "number", "description": "Total number of active listings" }, "totalOfferCount": { "type": "number", "description": "Total number of active offers" }, "totalProductCount": { "type": "number", "description": "Total number of products with active orderbook entries" }, "updatedAt": { "type": "string", "description": "When the stats were last calculated" } }, "required": [ "totalAskAmount", "totalBidAmount", "totalListingCount", "totalOfferCount", "totalProductCount", "updatedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/organization/get-organization/v1": { "get": { "summary": "Get organization details", "tags": [ "Organization" ], "description": "Get the organization details associated with the authenticated API key. Sensitive fields such as access tokens and internal IDs are excluded.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tradingEnabled": { "type": "boolean" }, "vacationMode": { "type": "boolean" }, "payoutMethod": { "type": "string" }, "electronicCheckName": { "type": "string" }, "electronicCheckEmail": { "type": "string" }, "apiEnabled": { "type": "boolean" }, "onboardingStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "createdAt", "updatedAt", "tradingEnabled", "vacationMode", "payoutMethod", "electronicCheckName", "electronicCheckEmail", "apiEnabled", "onboardingStatus" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/organization/update-organization/v1": { "patch": { "summary": "Update organization settings", "tags": [ "Organization" ], "description": "Update one or more settings for the authenticated organization. Only the provided fields will be modified. Supports vacation mode, payout method, and electronic check details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vacationMode": { "description": "Enable or disable vacation mode. When active, listings and offers are hidden from the marketplace.", "type": "boolean" }, "payoutMethod": { "description": "Default payout method for the organization", "type": "string", "enum": [ "electronic_check", "teller_ach" ] }, "electronicCheckName": { "description": "Payee name for electronic check payouts", "type": "string", "maxLength": 40 }, "electronicCheckEmail": { "description": "Payee email for electronic check payouts", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } } } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "vacationMode": { "type": "boolean" }, "payoutMethod": { "type": "string", "enum": [ "electronic_check", "teller_ach", "wire_transfer" ] }, "electronicCheckName": { "type": "string" }, "electronicCheckEmail": { "type": "string" } }, "required": [ "vacationMode", "payoutMethod", "electronicCheckName", "electronicCheckEmail" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/orders/get-purchase-orders/v1": { "get": { "summary": "List purchase orders", "tags": [ "Orders" ], "description": "List the purchase orders for the authenticated organization. Results are scoped to the API key's organization — you cannot access another organization's orders.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "pending_confirmation", "ready_for_shipment", "in_transit", "items_received", "check_in_progress", "order_complete", "order_cancelled", "check_in_complete" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by order status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of orders to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of orders to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "trackingIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending_confirmation", "ready_for_shipment", "in_transit", "items_received", "check_in_progress", "order_complete", "order_cancelled", "check_in_complete" ] }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "shipping": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Shipping fee in cents" }, "processingFee": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Processing fee in cents" }, "total": { "type": "number", "description": "Order total in cents" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completeAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "trackingIds", "status", "subtotal", "salesTax", "shipping", "processingFee", "total", "currency", "createdAt", "updatedAt", "completeAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/orders/get-sale-orders/v1": { "get": { "summary": "List sale orders", "tags": [ "Orders" ], "description": "List the sale orders for the authenticated organization. Results are scoped to the API key's organization — you cannot access another organization's orders.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "awaiting_payment", "payment_processing", "fufillment_in_progress", "payment_failed", "order_shipped", "order_complete", "order_cancelled", "partially_fufilled" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by order status" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of orders to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of orders to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "status": { "type": "string", "enum": [ "awaiting_payment", "payment_processing", "fufillment_in_progress", "payment_failed", "order_shipped", "order_complete", "order_cancelled", "partially_fufilled" ] }, "subtotal": { "type": "number", "description": "Subtotal in cents" }, "salesTax": { "type": "number", "description": "Sales tax in cents" }, "shipping": { "type": "number", "description": "Shipping fee in cents" }, "processingFee": { "type": "number", "description": "Processing fee in cents" }, "total": { "type": "number", "description": "Order total in cents" }, "currency": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "productId": { "type": "string" }, "variantId": { "type": "string" }, "price": { "type": "number", "description": "Price in cents" }, "quantity": { "type": "number" }, "tracking": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingService": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "item_recieved", "check_in_progress", "item_complete", "item_returned", "item_adjusted", "item_pending" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "productId", "variantId", "price", "quantity", "tracking", "shippingService", "status", "createdAt", "updatedAt" ], "additionalProperties": false } }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completeAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "status", "subtotal", "salesTax", "shipping", "processingFee", "total", "currency", "lineItems", "createdAt", "updatedAt", "completeAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/listings/create-listing/v1": { "post": { "summary": "Create a listing", "tags": [ "Listings" ], "description": "Create a new orderbook listing for the authenticated organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "price": { "description": "Price in cents. Required for fixed_pricing type", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "inventoryId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "maxSpotPrice": { "description": "Max spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "description": "Min spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "productId", "variantId", "quantity", "type" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "maxSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "expiresAt", "updatedAt", "createdAt", "sellerNotes", "premiumPercent", "type", "premiumDollar", "spotPremium", "quantity", "active", "spotPremiumDollar", "inventoryId", "maxSpotPrice", "minSpotPrice" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/listings/get-listings/v1": { "get": { "summary": "List your organization's orderbook listings", "tags": [ "Listings (Legacy)" ], "description": "Retrieve orderbook listings for the authenticated organization with optional filtering by active status and product ID. Results include related product and variant details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "active", "required": false, "description": "Filter by active status" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of listings to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of listings to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "expiresAt": { "type": "string" }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "inventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "expiresAt", "updatedAt", "createdAt", "sellerNotes", "premiumPercent", "type", "premiumDollar", "spotPremium", "quantity", "active", "spotPremiumDollar", "inventoryId", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/listings/get-listings/v2": { "get": { "summary": "List your organization's live listings", "tags": [ "Listings" ], "description": "Retrieve live orderbook listings for the authenticated organization. Only returns active, non-expired listings with valid pricing from trading-enabled organizations (via `orderbook_listing_live` view).\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of listings to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of listings to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "premiumPercent": { "type": "number" }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "type": "string" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inventoryId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "quantity", "premiumPercent", "premiumDollar", "type", "spotPremium", "spotPremiumDollar", "sellerNotes", "inventoryId", "active", "expiresAt", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/listings/get-listing-stats/v1": { "get": { "summary": "Get listing statistics for your organization", "tags": [ "Listings" ], "description": "Retrieve aggregate statistics about the authenticated organization's orderbook listings, including counts, quantities, and total value.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalListings": { "type": "number" }, "activeListings": { "type": "number" }, "inactiveListings": { "type": "number" }, "totalQuantity": { "type": "number" }, "totalValue": { "type": "number", "description": "Sum of price * quantity in cents" } }, "required": [ "totalListings", "activeListings", "inactiveListings", "totalQuantity", "totalValue" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/listings/delete-listing/v1": { "delete": { "summary": "Deactivate a listing", "tags": [ "Listings" ], "description": "Deactivate an orderbook listing owned by the authenticated organization. This sets the listing's active status to false rather than permanently deleting it.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "listingId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } } } } }, "/listings/update-listing/v1": { "patch": { "summary": "Update a listing", "tags": [ "Listings" ], "description": "Update fields on an orderbook listing owned by the authenticated organization. Only the provided fields will be updated.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listingId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "description": "Price in cents", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "quantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sellerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "listingId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "sellerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "active", "sellerNotes", "updatedAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/offers/create-offer/v1": { "post": { "summary": "Create an offer", "tags": [ "Offers" ], "description": "Create a new orderbook offer (bid) for the authenticated organization.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "price": { "description": "Price in cents. Required for fixed_pricing type", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "maxSpotPrice": { "description": "Max spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "description": "Min spot price in cents", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "productId", "variantId", "quantity", "type", "expiresAt" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "buyerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "maxSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "minSpotPrice": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "updatedAt", "expiresAt", "quantity", "buyerNotes", "createdAt", "premiumPercent", "type", "premiumDollar", "spotPremium", "active", "spotPremiumDollar", "maxSpotPrice", "minSpotPrice" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/offers/get-offers/v1": { "get": { "summary": "List your organization's orderbook offers", "tags": [ "Offers (Legacy)" ], "description": "Retrieve orderbook offers (bids) for the authenticated organization with optional filtering by active status and product ID. Results include related product and variant details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "active", "required": false, "description": "Filter by active status" }, { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of offers to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of offers to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "buyerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "premiumPercent": { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, "type": { "type": "string", "enum": [ "fixed_pricing", "premium_percentage_pricing", "premium_dollar_pricing" ] }, "premiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "spotPremium": { "anyOf": [ { "type": "number", "minimum": -140737488355328, "maximum": 140737488355327 }, { "type": "null" } ] }, "active": { "type": "boolean" }, "spotPremiumDollar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "updatedAt", "expiresAt", "quantity", "buyerNotes", "createdAt", "premiumPercent", "type", "premiumDollar", "spotPremium", "active", "spotPremiumDollar", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/offers/get-offers/v2": { "get": { "summary": "List your organization's live offers", "tags": [ "Offers" ], "description": "Retrieve live orderbook offers for the authenticated organization. Only returns active, non-expired offers with valid pricing from trading-enabled organizations (via `orderbook_offer_live` view).\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of offers to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of offers to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "quantity": { "type": "number" }, "premiumPercent": { "type": "number" }, "premiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "type": { "type": "string" }, "spotPremium": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "spotPremiumDollar": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "price", "quantity", "premiumPercent", "premiumDollar", "type", "spotPremium", "spotPremiumDollar", "active", "expiresAt", "createdAt", "updatedAt", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/offers/get-offer-stats/v1": { "get": { "summary": "Get offer statistics for your organization", "tags": [ "Offers" ], "description": "Retrieve aggregate statistics about the authenticated organization's orderbook offers (bids), including counts, quantities, and total value.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalOffers": { "type": "number" }, "activeOffers": { "type": "number" }, "inactiveOffers": { "type": "number" }, "totalQuantity": { "type": "number" }, "totalValue": { "type": "number", "description": "Sum of price * quantity in cents" } }, "required": [ "totalOffers", "activeOffers", "inactiveOffers", "totalQuantity", "totalValue" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/offers/delete-offer/v1": { "delete": { "summary": "Deactivate an offer", "tags": [ "Offers" ], "description": "Deactivate an orderbook offer owned by the authenticated organization. This sets the offer's active status to false rather than permanently deleting it.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "offerId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } } } } }, "/offers/update-offer/v1": { "patch": { "summary": "Update an offer", "tags": [ "Offers" ], "description": "Update fields on an orderbook offer owned by the authenticated organization. Only the provided fields will be updated.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "description": "Price in cents", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "quantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "buyerNotes": { "type": "string", "maxLength": 500 }, "active": { "type": "boolean" }, "premiumPercent": { "type": "number", "minimum": 0 }, "premiumDollar": { "description": "Premium in cents", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "offerId" ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "price": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "active": { "type": "boolean" }, "buyerNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "price", "quantity", "active", "buyerNotes", "updatedAt" ], "additionalProperties": false } }, "required": [ "success", "data" ], "additionalProperties": false } } } } } } }, "/inventory/get-inventory/v1": { "get": { "summary": "List your organization's inventory", "tags": [ "Inventory" ], "description": "Retrieve inventory items for the authenticated organization with optional filtering by product ID. Results include related product and variant details.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "in": "query", "name": "productId", "required": false, "description": "Filter by product ID" }, { "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of items to return (default 20, max 100)" }, { "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "in": "query", "name": "offset", "required": false, "description": "Number of items to skip (for pagination)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "productId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "variantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "quantity": { "type": "number" }, "purchasePricePer": { "type": "number", "description": "Purchase price per unit in cents" }, "purchaseSpotPrice": { "type": "number", "description": "Spot price at time of purchase in cents" }, "purchaseDate": { "type": "string" }, "purchaseSource": { "type": "string" }, "notes": { "type": "string" }, "certificateId": { "type": "string" }, "storedAt": { "type": "string" }, "createdAt": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" }, "sku": { "type": "string" }, "material": { "type": "string" } }, "required": [ "id", "title", "sku", "material" ], "additionalProperties": false }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "productId", "variantId", "quantity", "purchasePricePer", "purchaseSpotPrice", "purchaseDate", "purchaseSource", "notes", "certificateId", "storedAt", "createdAt", "product", "variant" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } } } } }, "/inventory/get-inventory-stats/v1": { "get": { "summary": "Get inventory statistics for your organization", "tags": [ "Inventory" ], "description": "Retrieve aggregate statistics about the authenticated organization's inventory, including total items, quantities, cost basis, and unique product count.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "totalItems": { "type": "number" }, "totalQuantity": { "type": "number" }, "totalCostBasis": { "type": "number", "description": "Sum of purchase_price_per * quantity across all inventory in cents" }, "uniqueProducts": { "type": "number" } }, "required": [ "totalItems", "totalQuantity", "totalCostBasis", "uniqueProducts" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/healthcheck/v1": { "get": { "summary": "Marketplace API healthcheck", "tags": [ "Root" ], "description": "Returns the health status of the Marketplace API.\n\n**Rate limit:** 120 requests burst, 60 requests/minute sustained.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "timestamp": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "timestamp", "service" ], "additionalProperties": false } } } } } } } }, "servers": [ { "url": "https://api.collectpure.com/", "description": "Production server" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Root", "description": "API information and status" }, { "name": "Products", "description": "Enriched product endpoints — full product details, search, and catalog metadata" }, { "name": "Listings", "description": "Listing management — create, update, deactivate, list, and view statistics" }, { "name": "Offers", "description": "Offer management — create, update, deactivate, list, and view statistics" }, { "name": "Orders", "description": "Purchase and sale order management for authenticated organizations" }, { "name": "Marketplace", "description": "Spot prices, marketplace statistics, shipping dates, and sitemap data" }, { "name": "Organization", "description": "Organization details and settings management" }, { "name": "Inventory", "description": "Inventory management — view items and aggregate statistics for your organization" }, { "name": "Products (Legacy)", "description": "Legacy product endpoints — use the enriched Products endpoints instead" }, { "name": "Listings (Legacy)", "description": "Legacy listing endpoints — use Orderbook endpoints instead" }, { "name": "Offers (Legacy)", "description": "Legacy offer endpoints — use Orderbook endpoints instead" } ] }