StyleGPT

REST API v1 Documentation

Complete reference for StyleGPT's latest API endpoints

API Status: Operational
Last Updated: Today

StyleGPT REST API v1 Documentation

Overview

The StyleGPT REST API v1 provides endpoints for AI-powered fashion styling, outfit generation, dataset management, search functionality, and asset generation. This API follows RESTful principles and supports JSON request/response formats.

Base URL

https://api.stylegpt.com/api/v1

Authentication

All API endpoints require authentication via API keys. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Rate Limiting

The API implements different rate limits based on your subscription tier:

Subscription Tiers and Rate Limits

DEMO Tier (Free)

  • Datasets: No access (0 rpm)
  • Assets/Images/Outfit: 20 rpm, unlimited quota
  • Chat: 20 rpm, unlimited quota
  • Search/Text: 20 rpm, unlimited quota
  • Search/Embedding: No access (0 rpm)

Starter Plan

  • Datasets: 60 rpm, unlimited quota
  • Assets/Images/Outfit: No access (0 rpm)
  • Chat: 20 rpm, 1,000 monthly quota
  • Search/Text: 20 rpm, 1,000 monthly quota
  • Search/Embedding: 20 rpm, 1,000 monthly quota

Pro Plan

  • Datasets: 100 rpm, unlimited quota
  • Assets/Images/Outfit: No access (0 rpm)
  • Chat: 50 rpm, 10,000 monthly quota
  • Search/Text: 50 rpm, 10,000 monthly quota
  • Search/Embedding: 50 rpm, 10,000 monthly quota

Enterprise Plan

  • Datasets: 200 rpm, unlimited quota
  • Assets/Images/Outfit: 1,000 rpm, 500,000 monthly quota
  • Chat: 200 rpm, 100,000 monthly quota
  • Search/Text: 200 rpm, 100,000 monthly quota
  • Search/Embedding: 200 rpm, 100,000 monthly quota

API Endpoints

Chat Endpoint

POST /chat

Generate AI-powered outfit suggestions and styling advice using Stylor's fashion intelligence.

Features:

  • Basic styling guidance (all tiers)
  • Multi-language support with automatic language detection
  • Structured function calling for outfit generation
  • Dynamic, relevant follow-up suggestions
  • Brand-specific inventory filtering
  • Warnings for non-active datasets or ignored/unsupported content types

Request Body

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "I need a professional outfit for a business meeting"
        }
      ]
    }
  ],
  "datasetIds": ["optional-dataset-id"],
  "chatId": "optional-chat-id",
  "brand": "optional-brand-filter",
  "useAdvancedStyling": false
}

Parameters

Parameter Type Required Description
messages Array Yes Array of conversation messages. Must contain at least one valid message.
messages[].role String Yes Message role: "user" or "assistant". Other roles are not accepted.
messages[].content Array / String Yes Array of content objects, or a string (will be wrapped as input_text).
messages[].content[].type String Conditional One of "input_text", "output_text", or "refusal". Other types are ignored with a warning.
messages[].content[].text String Conditional Required if type is "input_text", "output_text", or "refusal".
datasetIds Array<String> No Dataset IDs to use. If omitted, the active dataset is used. Draft/archived datasets are allowed but return warnings.
chatId String No Optional chat session identifier for conversation tracking.
brand String No Filter results by a specific brand in the dataset.
useAdvancedStyling Boolean No Enable web search for current trends (Enterprise only, default: false).

Successful Response

{
  "message": "I'll help you create a professional business meeting outfit! Based on current inventory, here's a polished look:",
  "functionCall": {
    "name": "generateOutfit",
    "arguments": {
      "descriptions": [
        "Men's slim-fit navy wool suit jacket",
        "Men's slim-fit navy wool suit trousers",
        "Men's white cotton dress shirt",
        "Men's silk navy tie",
        "Men's black leather oxford shoes"
      ]
    }
  },
  "persona": "Professional business attire for corporate meetings",
  "followUps": [
    "Make it more casual",
    "Try different colors",
    "Add accessories",
    "Show alternative options"
  ],
  "lang": "en",
  "warnings": [
    "Dataset \\"abc123\\" is in draft mode and may not contain complete or production-ready data.",
    "Message 0 content item 2 has unsupported type 'image_url' and was ignored."
  ]
}

Notes:

  • warnings is optional and included only if there were issues with dataset status or ignored/invalid message content.
  • functionCall.arguments is always parsed as an object. If no call is needed, functionCall will contain name: "" and arguments: {}.

Error Responses

Status Description
400 Missing or invalid organizationId in request context, invalid datasetIds format, or invalid request sent to AI service.
422 Invalid messages array or structure (e.g., missing role/content, invalid content type, non-array datasetIds).
404 No active datasets found (when none provided) OR brand inventory data not found for selected datasets.
429 AI service rate limit exceeded.
500 Internal server error.
502 AI service temporarily unavailable, authentication failure, invalid AI response format, or unparsable AI JSON.
503 Service temporarily unavailable due to backend connection or database issue.
504 Request to AI service or backend timed out.

Asset Generation

POST /assets/images/outfit

Generate high-resolution, full-body outfit images using Google's Gemini 2.0 Flash model for image generation.

Availability: DEMO tier (20 rpm) and Enterprise tier (1,000 rpm) only.

Request Body

{
  "imageUrls": [
    "https://example.com/shirt.jpg",
    "https://example.com/pants.jpg", 
    "https://example.com/shoes.jpg"
  ],
  "modelDescription": "25-year-old professional woman, 5'7\", athletic build, standing confidently"
}

Parameters

Parameter Type Required Description
imageUrls Array Yes Array of clothing item image URLs (max 10 items)
modelDescription String Yes Physical description of the model (max 500 characters)

Response

{
  "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Error Responses

Status Description
422 Invalid parameters (empty array, >10 images, >500 char description, invalid URLs, image fetch errors)
500 Image generation failed or processing error

Search Endpoints

POST /search/text

Search clothing datasets using natural language text queries with CLIP multimodal embeddings for semantic similarity matching.

Request Body

{
  "query": "blue denim jacket for women",
  "filters": {
    "metadata.gender": "Female",
    "metadata.articleType": "Jacket"
  },
  "limit": 10
}

Parameters

Parameter Type Required Description
query String Yes Search query (max 512 characters)
filters Object No MongoDB-style filters for results
limit Number No Number of results to return (1-100, default: 5)

Response

{
  "results": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "productId": "PROD123",
      "variantId": "VAR456",
      "metadata": {
        "gender": "Female",
        "fit": "regular fit", 
        "description": {
          "concise": "Women's classic denim jacket",
          "detailed": "A timeless denim jacket crafted from premium cotton with button closure",
          "keyword": "denim jacket"
        },
        "articleType": "Jacket",
        "formality": "casual",
        "pattern": "solid"
      },
      "product": {
        "sku": "DJ001-BLUE-M",
        "color": {
          "name": "Blue",
          "rgbValue": [70, 130, 180]
        },
        "url": "https://retailer.com/products/denim-jacket",
        "name": "Classic Denim Jacket",
        "description": "Premium cotton denim jacket with vintage styling",
        "careInstructions": "Machine wash cold, tumble dry low",
        "price": 89.99,
        "currency": "USD",
        "images": [
          {
            "_id": "img_001",
            "originalImageUrl": "https://retailer.com/jacket-front.jpg",
            "type": "Model",
            "uploaded": {
              "id": "upload_123",
              "url": "https://cdn.stylegpt.com/images/jacket-front.jpg"
            }
          }
        ],
        "sizes": [
          {
            "_id": "size_001", 
            "inStock": true,
            "inventoryQuantity": "12",
            "price": 89.99,
            "label": "Medium",
            "sku": "DJ001-BLUE-M"
          }
        ]
      },
      "origin": {
        "siteUrl": "https://retailer.com",
        "brandId": "brand_123", 
        "brand": "Fashion Brand",
        "country": "US"
      },
      "score": 0.92,
      "embeddings": {},
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

POST /search/embedding

Search clothing datasets using pre-computed 512-dimensional embedding vectors from CLIP model for precise semantic matching.

Request Body

{
  "embedding": [0.1, 0.2, -0.3, ..., 0.8],
  "filters": {
    "metadata.articleType": "Dress",
    "metadata.gender": "Female"
  },
  "limit": 5
}

Parameters

Parameter Type Required Description
embedding Array Yes Exactly 512-dimensional embedding vector (CLIP multimodal)
filters Object No MongoDB-style filters for results
limit Number No Number of results to return (1-100, default: 5)

Response

Same structure as text search response, with results ordered by vector similarity score.

Error Responses (Search Endpoints)

Status Description
422 Invalid query/embedding parameters (wrong dimensions, invalid filters, limit out of range)
500 Database error or embedding processing failed

Dataset Management

Availability: Starter (60 rpm), Pro (100 rpm), and Enterprise (200 rpm) plans only.

POST /datasets

Create a new clothing dataset for organizing and managing fashion items within your organization.

Request Body

{
  "name": "Summer Collection 2024",
  "description": "Lightweight clothing items for summer season"
}

Parameters

Parameter Type Required Description
name String Yes Dataset name (required, non-empty after trimming)
description String No Optional dataset description

Response

{
  "datasetId": "550e8400-e29b-41d4-a716-446655440000"
}

GET /datasets

List all datasets for your organization with pagination support.

Query Parameters

Parameter Type Default Description
page Number 1 Page number (1-based, positive integer)
limit Number 50 Items per page (1-200, default: 50)

Response

{
  "datasets": [
    {
      "datasetId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "active",
      "name": "Summer Collection 2024", 
      "description": "Lightweight clothing items for summer season",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

GET /datasets/{datasetId}

Retrieve details of a specific dataset.

Path Parameters

Parameter Type Description
datasetId String Unique dataset identifier (UUID)

Response

{
  "dataset": {
    "datasetId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "name": "Summer Collection 2024",
    "description": "Lightweight clothing items for summer season", 
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

DELETE /datasets/{datasetId}

Delete a dataset and all its associated items permanently.

Path Parameters

Parameter Type Description
datasetId String Unique dataset identifier (UUID)

Response

{
  "message": "Dataset successfully deleted",
  "deletedId": "550e8400-e29b-41d4-a716-446655440000"
}

PATCH /datasets/{datasetId}/activate

Change dataset status from 'draft' or 'archived' to 'active' to make it available for search operations.

Path Parameters

Parameter Type Description
datasetId String Unique dataset identifier (UUID)

Response

{
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}

PATCH /datasets/{datasetId}/archive

Change dataset status to 'archived' to temporarily remove from search operations while preserving data.

Path Parameters

Parameter Type Description
datasetId String Unique dataset identifier (UUID)

Response

{
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "archived",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}

Dataset Items Management

POST /datasets/{datasetId}/items/upload

Upload clothing items to a specific dataset. Items are queued for processing with embedding generation and validation.

Upload Limits: Maximum 5,000 items per request.

Path Parameters

Parameter Type Description
datasetId String Target dataset identifier (UUID)

Request Body

{
  "items": [
    {
      "name": "Summer Floral Dress",
      "handle": "summer-floral-dress",
      "description": "Light and airy floral dress perfect for summer occasions",
      "publishedAt": "2024-01-15T09:00:00.000Z",
      "createdAt": "2024-01-15T08:30:00.000Z", 
      "updatedAt": "2024-01-15T08:30:00.000Z",
      "productType": "Dress",
      "sku": "SFD001",
      "price": 79.99,
      "tags": ["summer", "floral", "casual", "feminine"],
      "variants": [
        {
          "sku": "SFD001-S",
          "name": "Summer Floral Dress - Small",
          "available": true,
          "price": 79.99,
          "createdAt": "2024-01-15T08:30:00.000Z",
          "updatedAt": "2024-01-15T08:30:00.000Z", 
          "productId": "SFD001"
        }
      ],
      "images": [
        {
          "src": "https://example.com/dress-front.jpg"
        },
        {
          "src": "https://example.com/dress-back.jpg" 
        }
      ],
      "options": [
        {
          "name": "Size",
          "values": ["Small", "Medium", "Large", "XL"]
        },
        {
          "name": "Color", 
          "values": ["Floral Print"]
        }
      ]
    }
  ]
}

Item Schema Requirements

Field Type Required Description
name String Yes Product name
handle String Yes URL-friendly product identifier
description String Yes Product description
publishedAt String Yes ISO 8601 date string
createdAt String Yes ISO 8601 date string
updatedAt String Yes ISO 8601 date string
productType String Yes Category/type of product
sku String Yes Unique product SKU
price Number Yes Product price (non-negative)
tags Array Yes Array of tag strings
variants Array Yes Array of product variant objects
images Array Yes Array of image objects with src property
options Array Yes Array of option objects with name and values

Response

{
  "success": true,
  "uploaded": 1,
  "warnings": [
    {
      "index": 0,
      "path": "description", 
      "message": "Description could be more detailed"
    }
  ]
}

Error Response (Validation Failed)

{
  "error": "Validation failed.",
  "details": [
    {
      "index": 0,
      "path": "price",
      "message": "Price must be a non-negative number."
    },
    {
      "index": 0,
      "path": "variants[0].sku", 
      "message": "Expected string."
    }
  ]
}

GET /datasets/{datasetId}/items

List all processed items in a specific dataset with pagination.

Path Parameters

Parameter Type Description
datasetId String Dataset identifier (UUID)

Query Parameters

Parameter Type Default Description
page Number 1 Page number (1-based)
limit Number 50 Items per page (1-200)

Response

{
  "items": [
    {
      "organizationId": "org_123",
      "datasetId": "550e8400-e29b-41d4-a716-446655440000",
      "itemId": "item_456", 
      "metadata": {
        "gender": "Female",
        "fit": "regular fit",
        "description": {
          "concise": "Women's summer dress",
          "detailed": "Light and airy floral dress perfect for summer",
          "keyword": "summer dress"
        },
        "articleType": "Dress",
        "formality": "casual",
        "pattern": "floral"
      },
      "product": {
        "sku": "SFD001",
        "color": {
          "name": "Floral Print"
        },
        "url": "https://retailer.com/summer-dress",
        "name": "Summer Floral Dress",
        "description": "Light and airy floral dress",
        "careInstructions": "Machine wash cold",
        "price": 79.99,
        "currency": "USD",
        "images": [],
        "sizes": []
      },
      "origin": {
        "siteUrl": "https://retailer.com",
        "brandId": "brand_123",
        "brand": "Fashion Brand", 
        "country": "US"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50, 
    "total": 1,
    "hasMore": false
  }
}

GET /datasets/{datasetId}/items/{itemId}

Retrieve details of a specific processed item within a dataset.

Path Parameters

Parameter Type Description
datasetId String Dataset identifier (UUID)
itemId String Item identifier

Response

Returns the same item structure as shown in the list items response, but for a single item.

DELETE /datasets/{datasetId}/items/{itemId}

Delete a specific processed item from a dataset permanently.

Path Parameters

Parameter Type Description
datasetId String Dataset identifier (UUID)
itemId String Item identifier

Response

{
  "message": "Item successfully deleted",
  "deletedId": "item_456"
}

Queue Management

GET /datasets/{datasetId}/items/queue

List items currently being processed in the upload queue for a dataset.

Path Parameters

Parameter Type Description
datasetId String Dataset identifier (UUID)

Query Parameters

Parameter Type Default Description
page Number 1 Page number (1-based)
limit Number 50 Items per page (1-200)

Response

{
  "items": [
    {
      "itemId": "queue_789",
      "organizationId": "org_123",
      "datasetId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending",
      "data": {
        "name": "Summer Floral Dress",
        "handle": "summer-floral-dress",
        "description": "Light and airy floral dress",
        "sku": "SFD001",
        "price": 79.99,
        "variants": [],
        "images": [],
        "options": []
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

Queue Status Values

Status Description
pending Item is queued for processing
complete Item has been processed successfully
failed Item processing failed

GET /datasets/{datasetId}/items/queue/{itemId}

Retrieve status and details of a specific queued item.

Path Parameters

Parameter Type Description
datasetId String Dataset identifier (UUID)
itemId String Queued item identifier

Response

Returns the same queued item structure as shown in the queue list response.

DELETE /datasets/{datasetId}/items/queue/{itemId}

Cancel/delete a queued item that hasn't completed processing.

Path Parameters

Parameter Type Description
datasetId String Dataset identifier (UUID)
itemId String Queued item identifier

Response

{
  "message": "Queued item successfully cancelled",
  "cancelledId": "queue_789"
}

Dataset Status Values

Status Description
draft Dataset is created but not active for search
active Dataset is live and available for search operations
archived Dataset is temporarily disabled but data preserved

Error Handling

All endpoints return standard HTTP status codes and JSON error responses:

Common Error Response Format

{
  "error": "Error message description"
}

HTTP Status Codes

Code Description
200 Success
400 Bad Request - Invalid request format
401 Unauthorized - Invalid or missing API key
403 Forbidden - Insufficient permissions for subscription tier
404 Not Found - Resource doesn't exist or organization/dataset not found
422 Unprocessable Entity - Invalid parameters or validation failed
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server-side error
502 Bad Gateway - External service error (AI providers)
503 Service Unavailable - Temporary service issues
504 Gateway Timeout - Request timeout

Rate Limit Headers

All API responses include rate limiting information in the headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1642685400
X-RateLimit-Quota: 1000
X-RateLimit-Quota-Remaining: 999

Code Examples

Chat API Example

const response = await fetch('https://api.stylegpt.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    messages: [{
      role: 'user',
      content: [{
        type: 'text',
        text: 'I need a casual outfit for weekend brunch'
      }]
    }],
    useAdvancedStyling: false
  })
});

const data = await response.json();
console.log(data.responseMessage);
if (data.functionCall?.name === 'generateOutfit') {
  console.log('Suggested items:', data.functionCall.parameters.descriptions);
}

Text Search Example

const searchResponse = await fetch('https://api.stylegpt.com/api/v1/search/text', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    query: 'comfortable running shoes for women',
    filters: {
      'metadata.gender': 'Female',
      'metadata.articleType': 'Shoes'
    },
    limit: 10
  })
});

const searchData = await searchResponse.json();
searchData.results.forEach(item => {
  console.log(`${item.product.name} - $${item.product.price} (Score: ${item.score})`);
});

Dataset Creation and Upload Example

// Create dataset
const datasetResponse = await fetch('https://api.stylegpt.com/api/v1/datasets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: 'My Fashion Collection',
    description: 'Custom clothing items for my store'
  })
});

const { datasetId } = await datasetResponse.json();

// Upload items to dataset
const uploadResponse = await fetch(`https://api.stylegpt.com/api/v1/datasets/${datasetId}/items/upload`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    items: [{
      name: 'Classic White T-Shirt',
      handle: 'classic-white-tshirt',
      description: 'Premium cotton basic tee perfect for layering',
      publishedAt: new Date().toISOString(),
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      productType: 'T-Shirt',
      sku: 'CWT001',
      price: 29.99,
      tags: ['basic', 'cotton', 'white', 'casual'],
      variants: [{
        sku: 'CWT001-M',
        name: 'Classic White T-Shirt - Medium',
        available: true,
        price: 29.99,
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
        productId: 'CWT001'
      }],
      images: [{
        src: 'https://example.com/tshirt-front.jpg'
      }],
      options: [{
        name: 'Size',
        values: ['XS', 'S', 'M', 'L', 'XL']
      }]
    }]
  })
});

const uploadData = await uploadResponse.json();
console.log(`Uploaded ${uploadData.uploaded} items successfully`);

Best Practices

  1. API Key Security: Never expose API keys in client-side code. Always use server-side proxy endpoints.

  2. Rate Limiting: Implement exponential backoff when receiving 429 responses.

  3. Error Handling: Always check response status codes and handle errors gracefully.

  4. Pagination: Use pagination for large datasets to improve performance and reduce memory usage.

  5. Data Validation: Validate data structures before sending requests to avoid 422 validation errors.

  6. Date Formats: Always use ISO 8601 date strings (e.g., "2024-01-15T10:30:00.000Z").

  7. SKU Uniqueness: Ensure SKUs are unique within your organization to prevent upload conflicts.

  8. Image URLs: Ensure image URLs are publicly accessible and use HTTPS.

  9. Embedding Search: Use text search for natural language queries; use embedding search only when you have pre-computed vectors.

  10. Queue Monitoring: Monitor the queue status when uploading large batches of items.

Support

For API support, documentation updates, or technical assistance:

StyleGPT REST API v1 Documentation - Last updated: January 2025

Ready to get started?

Test our APIs in the interactive playground or generate your API keys.

Try API PlaygroundGet API Keys