Catalog API Documentation

Modified on Mon, 17 Feb at 12:30 PM

Base URL

https://example.com/api/catalog/1.0/items/

Endpoints

List Items

GET items

Retrieve a list of items.

Parameters

brand: (required) Filter items by brand name.
page: (optional) Page number for pagination.

Response

{
    "links": {
        "next": "https://example.com/api/catalog/1.0/items/?page=2",
        "previous": null
    },
    "count": 100,
    "data": [
        {
            "id": 1,
            "brand": "Brand Name",
            "slug": "item-slug",
            "stock_number": "12345",
            "style_number": "67890",
            "name": "Item Name",
            "description": "Item Description",
            "department": "Department Name",
            "item_type": {
                "name": "Type Name",
                "plural_name": "Types"
            },
            "item_sub_types": ["SubType1", "SubType2"],
            "styles": ["Style1", "Style2"],
            "collection": "Collection Name",
            "collections": ["Collection1", "Collection2"],
            "categories": ["Category1", "Category2"],
            "matching_item": "12345",
            "related_items": ["12346", "12347"],
            "media": [
                {
                    "type": "image",
                    "angle": "front",
                    "materials": ["Material1", "Material2"],
                    "image": "https://example.com/image.jpg",
                    "video": null,
                    "video_url": null,
                    "html_embed": null
                }
            ],
            "prices": [
                {
                    "cost": 100.0,
                    "price": 150.0,
                    "retail_price": 200.0,
                    "default_price": 150.0,
                    "material": "Gold"
                }
            ],
            "variants": [
                {
                    "id": 1,
                    "name": "Variant Name",
                    "slug": "variant-slug",
                    "description": "Variant Description",
                    "price": 150.0,
                    "retail_price": 200.0,
                    "cost": 100.0,
                    "stock_number": "12345-1",
                    "style_number": "67890-1",
                    "active": true,
                    "item_option_value": [
                        {
                            "id": 1,
                            "name": "Option Value",
                            "item_option": {
                                "id": 1,
                                "name": "Option Name"
                            }
                        }
                    ]
                }
            ],
            "availability": "In Stock",
            "price_notes": "Special discount available",
            "details": "Detailed description",
            "total_carat_weight": "1.5",
            "gender": "Unisex",
            "materials": ["Gold", "Diamond"],
            "settings": ["Prong", "Bezel"],
            "setting_types": ["Type1", "Type2"],
            "width": "5mm",
            "ring_size_lower": "6",
            "ring_size_upper": "8",
            "fit": "Comfort",
            "length": "18 inches",
            "diameter": "10mm",
            "ring_width_lower": "4mm",
            "ring_width_upper": "6mm",
            "earring_backing": "Screw Back",
            "clasp": "Lobster"
        }
    ]
}

Authentication

The API requires authentication. Ensure you include the appropriate authentication headers in your requests. You'll receive these from Thinkspace. Include the following header in your requests:

Authorization: Token <your-token>

Pagination

The API supports pagination. Use the page and page_size query parameters to navigate through paginated results.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request.

Models

Item

id: UUID
brand: String
slug: String
stock_number: String
style_number: String
name: String
description: String
department: String
item_type: Object
item_sub_types: List of Strings
styles: List of Strings
collection: String
collections: List of Strings
categories: List of Strings
matching_item: String
related_items: List of Strings
media: List of Media Objects
prices: List of Price Objects
variants: List of Variant Objects

Media

type: String
angle: String
materials: List of Strings
image: URL
video: URL
video_url: URL
html_embed: String

Price

cost: Float
price: Float
retail_price: Float
default_price: Float
material: String

Variant

id: UUID
name: String
slug: String
description: String
price: Float
retail_price: Float
cost: Float
stock_number: String
style_number: String
active: Boolean
item_option_value: List of Option Value Objects

Option Value

id: UUID
name: String
item_option: Object

Option

id: UUID
name: String

Additional Attributes

availability: String
price_notes: String
details: String
total_carat_weight: String
gender: String
materials: List of Strings
settings: List of Strings
setting_types: List of Strings
width: String
ring_size_lower: String
ring_size_upper: String
fit: String
length: String
diameter: String
ring_width_lower: String
ring_width_upper: String
earring_backing: String
clasp: String