Products API

The Products API provides access to the complete OSUS.AI product catalog, including furniture, appliances, building materials, and home décor items with rich metadata, 3D models, and AR support.

Base URL: https://api.osus.ai/v1/products

Key Features

3D models and AR support

Arabic and English content

Advanced filtering and search

Real-time inventory tracking

List Products

Retrieve a paginated list of products with filtering and sorting options.

GET /products

Query Parameters

Parameter	Type	Description	Example
`page`	integer	Page number (default: 1)	1
`limit`	integer	Items per page (default: 20, max: 100)	20
`category`	string	Filter by category slug	furniture
`brand`	string	Filter by brand name	ikea
`minPrice`	number	Minimum price filter	100
`maxPrice`	number	Maximum price filter	5000
`search`	string	Search query	modern sofa
`sortBy`	string	Sort field: price, name, rating, created	price
`sortOrder`	string	Sort order: asc, desc	asc
`inStock`	boolean	Filter by stock availability	true
`has3D`	boolean	Filter products with 3D models	true
`hasAR`	boolean	Filter products with AR support	true
`color`	string[]	Filter by colors (comma-separated)	white,black
`material`	string[]	Filter by materials	wood,metal

Example Request

curl -X GET 'https://api.osus.ai/v1/products?category=furniture&brand=ikea&minPrice=100&maxPrice=1000&sortBy=price&sortOrder=asc&limit=20' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "sku": "IKEA-SOFA-001",
        "name": {
          "ar": "أريكة مودرن ثلاثية",
          "en": "Modern 3-Seat Sofa"
        },
        "slug": "modern-3-seat-sofa",
        "category": {
          "id": "cat-001",
          "name": "Living Room Furniture",
          "slug": "living-room-furniture"
        },
        "brand": {
          "id": "brand-001",
          "name": "IKEA",
          "logo": "https://cdn.osus.ai/brands/ikea-logo.png"
        },
        "pricing": {
          "basePrice": 2500,
          "salePrice": 2000,
          "currency": "EGP",
          "discountPercentage": 20
        },
        "inventory": {
          "stockQuantity": 15,
          "stockStatus": "in_stock",
          "allowBackorder": false
        },
        "media": {
          "images": [
            {
              "url": "https://cdn.osus.ai/products/sofa-001-main.jpg",
              "alt": "Modern 3-Seat Sofa",
              "isPrimary": true
            }
          ],
          "threeDModel": {
            "url": "https://cdn.osus.ai/3d/sofa-001.glb",
            "format": "glb"
          },
          "arModel": {
            "iosUrl": "https://cdn.osus.ai/ar/sofa-001.usdz",
            "androidUrl": "https://cdn.osus.ai/ar/sofa-001.glb"
          }
        },
        "specifications": {
          "dimensions": {
            "length": 200,
            "width": 85,
            "height": 75,
            "weight": 45
          },
          "material": "Fabric",
          "color": "Gray",
          "style": "Modern"
        },
        "features": {
          "isFeatured": true,
          "isNew": false,
          "hasInstallation": true,
          "has3D": true,
          "hasAR": true,
          "isCustomizable": true
        },
        "ratings": {
          "average": 4.5,
          "count": 127
        },
        "createdAt": "2025-01-10T08:00:00Z",
        "updatedAt": "2025-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1250,
      "totalPages": 63,
      "hasNext": true,
      "hasPrev": false
    },
    "facets": {
      "categories": [
        {
          "id": "living-room",
          "name": "Living Room",
          "count": 450
        },
        {
          "id": "bedroom",
          "name": "Bedroom",
          "count": 320
        }
      ],
      "brands": [
        {
          "id": "ikea",
          "name": "IKEA",
          "count": 180
        },
        {
          "id": "home-center",
          "name": "Home Center",
          "count": 95
        }
      ],
      "priceRanges": [
        {
          "min": 0,
          "max": 500,
          "count": 245
        },
        {
          "min": 500,
          "max": 1000,
          "count": 380
        }
      ]
    }
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req_123456"
}

Get Product Details

Retrieve detailed information about a specific product.

GET /products/{productId}

Path Parameters

Parameter	Type	Description
`productId`	string	Product UUID or SKU

Query Parameters

Parameter	Type	Description
`include`	string	Include related data: variants,reviews,specifications
`lang`	string	Language preference: ar, en

Example Request

curl -X GET 'https://api.osus.ai/v1/products/550e8400-e29b-41d4-a716-446655440000?include=variants,reviews' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept-Language: ar"

Product Variants

Get all variants of a specific product (different colors, sizes, materials).

GET /products/{productId}/variants

Example Response

{
  "success": true,
  "data": {
    "variants": [
      {
        "id": "var-001",
        "sku": "IKEA-SOFA-001-GRAY",
        "name": {
          "ar": "رمادي",
          "en": "Gray"
        },
        "color": "Gray",
        "material": "Fabric",
        "priceAdjustment": 0,
        "stockQuantity": 15,
        "images": [
          {
            "url": "https://cdn.osus.ai/products/sofa-001-gray.jpg",
            "alt": "Gray Sofa Variant"
          }
        ],
        "isActive": true
      },
      {
        "id": "var-002",
        "sku": "IKEA-SOFA-001-BLUE",
        "name": {
          "ar": "أزرق",
          "en": "Blue"
        },
        "color": "Blue",
        "material": "Fabric",
        "priceAdjustment": 200,
        "stockQuantity": 8,
        "images": [
          {
            "url": "https://cdn.osus.ai/products/sofa-001-blue.jpg",
            "alt": "Blue Sofa Variant"
          }
        ],
        "isActive": true
      }
    ]
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "requestId": "req_123457"
}

Product Categories

Browse the hierarchical product category structure.

GET /categories

GET /categories/{categoryId}/products

Example Response

{
  "success": true,
  "data": {
    "categories": [
      {
        "id": "cat-001",
        "name": {
          "ar": "أثاث",
          "en": "Furniture"
        },
        "slug": "furniture",
        "parentId": null,
        "level": 0,
        "productCount": 1250,
        "children": [
          {
            "id": "cat-002",
            "name": {
              "ar": "غرفة المعيشة",
              "en": "Living Room"
            },
            "slug": "living-room",
            "parentId": "cat-001",
            "level": 1,
            "productCount": 450
          }
        ],
        "image": "https://cdn.osus.ai/categories/furniture.jpg",
        "icon": "fas fa-couch"
      }
    ]
  }
}

3D Models & AR

Access 3D models and AR assets for products.

GET /products/{productId}/3d-model

3D Model Response

{
  "success": true,
  "data": {
    "model": {
      "formats": {
        "glb": {
          "url": "https://cdn.osus.ai/3d/sofa-001.glb",
          "size": 2457600,
          "quality": "high"
        },
        "gltf": {
          "url": "https://cdn.osus.ai/3d/sofa-001.gltf",
          "size": 1890432,
          "quality": "medium"
        }
      },
      "ar": {
        "ios": {
          "url": "https://cdn.osus.ai/ar/sofa-001.usdz",
          "size": 3145728
        },
        "android": {
          "url": "https://cdn.osus.ai/ar/sofa-001.glb",
          "size": 2457600
        }
      },
      "dimensions": {
        "length": 2.0,
        "width": 0.85,
        "height": 0.75
      },
      "materials": [
        {
          "name": "fabric",
          "color": "#808080",
          "roughness": 0.8,
          "metallic": 0.0
        }
      ]
    }
  }
}

Inventory Status

Check real-time inventory status for products.

GET /products/{productId}/inventory

Inventory Response

{
  "success": true,
  "data": {
    "inventory": {
      "productId": "550e8400-e29b-41d4-a716-446655440000",
      "stockQuantity": 15,
      "reservedQuantity": 3,
      "availableQuantity": 12,
      "stockStatus": "in_stock",
      "lowStockThreshold": 5,
      "allowBackorder": false,
      "estimatedRestockDate": null,
      "warehouses": [
        {
          "id": "wh-cairo",
          "name": "Cairo Warehouse",
          "quantity": 10,
          "deliveryTime": "1-2 days"
        },
        {
          "id": "wh-alex",
          "name": "Alexandria Warehouse", 
          "quantity": 5,
          "deliveryTime": "2-3 days"
        }
      ]
    }
  }
}

Error Codes

HTTP Status	Error Code	Description
400	`INVALID_PARAMETERS`	Invalid query parameters provided
404	`PRODUCT_NOT_FOUND`	Product with specified ID not found
404	`CATEGORY_NOT_FOUND`	Category with specified ID not found
429	`RATE_LIMIT_EXCEEDED`	Too many requests, rate limit exceeded
500	`SEARCH_SERVICE_ERROR`	Search service temporarily unavailable