{
  "openapi": "3.1.0",
  "info": {
    "title": "StyleScore API",
    "version": "1",
    "description": "An outfit coach for garments and colour, never for bodies. Authenticate with an API key (Authorization: Bearer <key> or X-API-Key). Only starting an analysis is billed, after it succeeds; the preview, the scorer, the wardrobe and the history are free."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "security": [
    {
      "bearer": []
    },
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/api/v1/meta": {
      "get": {
        "summary": "Vocabularies",
        "operationId": "getMeta",
        "tags": [
          "Reference"
        ],
        "description": "Occasions, garment categories, style attributes and the colour vocabulary every request is validated against.",
        "responses": {
          "200": {
            "description": {
              "$ref": "#/components/schemas/Meta"
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/api/v1/preview": {
      "post": {
        "summary": "Preview a photo (free)",
        "operationId": "previewPhoto",
        "tags": [
          "Analysis"
        ],
        "description": "Local photo quality and the measured palette. No AI, never billed. Send JSON with a base64 `photo`, or multipart with a `photo` file.",
        "responses": {
          "200": {
            "description": {
              "$ref": "#/components/schemas/Preview"
            }
          },
          "415": {
            "description": "Not a JPEG or PNG"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/score": {
      "post": {
        "summary": "Score an outfit without a photo (free)",
        "operationId": "scoreOutfit",
        "tags": [
          "Analysis"
        ],
        "description": "Scores garments you describe for an occasion: colour harmony, contrast, formality, coherence, weather and preferences, with every verification check. Never billed.",
        "responses": {
          "200": {
            "description": {
              "$ref": "#/components/schemas/ScoreResult"
            }
          },
          "422": {
            "description": "Invalid garments or occasion"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScoreRequest"
              }
            }
          }
        }
      }
    },
    "/api/v1/analyses": {
      "post": {
        "summary": "Start an analysis (billed on success)",
        "operationId": "startAnalysis",
        "tags": [
          "Analysis"
        ],
        "description": "Queues one outfit analysis and returns 202 with a job to poll. The analysis is billed only when it is delivered; an unusable photo or a failure bills nothing. Send JSON with a base64 `photo`, or multipart with `photo`, `occasion`, `language`, `temperature_c`, `rain`.",
        "responses": {
          "202": {
            "description": {
              "$ref": "#/components/schemas/Accepted"
            }
          },
          "402": {
            "description": "Empty wallet"
          },
          "403": {
            "description": "No active subscription"
          },
          "415": {
            "description": "Not a JPEG or PNG"
          },
          "422": {
            "description": "Invalid occasion, weather or language"
          },
          "429": {
            "description": "Hourly quota reached"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartRequest"
              }
            }
          }
        }
      },
      "get": {
        "summary": "List analyses",
        "operationId": "listAnalyses",
        "tags": [
          "Analysis"
        ],
        "description": "Newest first.",
        "responses": {
          "200": {
            "description": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/AnalysisSummary"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ]
      }
    },
    "/api/v1/analyses/{id}": {
      "get": {
        "summary": "Get a delivered analysis",
        "operationId": "getAnalysis",
        "tags": [
          "Analysis"
        ],
        "description": "Garments, palette, scores with evidence, verification checks, suggestions with projected scores and wardrobe matches.",
        "responses": {
          "200": {
            "description": {
              "$ref": "#/components/schemas/Analysis"
            }
          },
          "404": {
            "description": "Not found or no longer retained"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/jobs/{id}": {
      "get": {
        "summary": "Poll a job",
        "operationId": "getJob",
        "tags": [
          "Analysis"
        ],
        "description": "queued, running, succeeded or failed; on failure `error` says what to do.",
        "responses": {
          "200": {
            "description": {
              "$ref": "#/components/schemas/Job"
            }
          },
          "404": {
            "description": "Not found"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/history": {
      "get": {
        "summary": "Style history",
        "operationId": "getHistory",
        "tags": [
          "History"
        ],
        "description": "Weekly averages, colour families, garment categories and occasions.",
        "responses": {
          "200": {
            "description": {
              "$ref": "#/components/schemas/History"
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ]
      }
    },
    "/api/v1/wardrobe": {
      "get": {
        "summary": "List wardrobe items",
        "operationId": "listWardrobe",
        "tags": [
          "Wardrobe"
        ],
        "description": "The pieces you own.",
        "responses": {
          "200": {
            "description": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Item"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "summary": "Add a wardrobe item",
        "operationId": "createWardrobeItem",
        "tags": [
          "Wardrobe"
        ],
        "description": "Owned pieces are used for suggestions and matches.",
        "responses": {
          "201": {
            "description": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "409": {
            "description": "Wardrobe limit reached"
          },
          "422": {
            "description": "Invalid item"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemInput"
              }
            }
          }
        }
      }
    },
    "/api/v1/wardrobe/{id}": {
      "delete": {
        "summary": "Delete a wardrobe item",
        "operationId": "deleteWardrobeItem",
        "tags": [
          "Wardrobe"
        ],
        "description": "",
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "Not found"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "properties": {
          "occasions": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "attrs": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "colors": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "families": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "slots": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "Weather": {
        "type": "object",
        "properties": {
          "temperature_c": {
            "type": "number"
          },
          "rain": {
            "type": "boolean"
          }
        }
      },
      "StartRequest": {
        "type": "object",
        "required": [
          "photo",
          "occasion"
        ],
        "properties": {
          "photo": {
            "type": "string",
            "description": "JPEG or PNG, base64 (data: URL accepted)"
          },
          "occasion": {
            "type": "string",
            "enum": [
              "interview",
              "business_formal",
              "business_casual",
              "smart_casual",
              "casual",
              "date_night",
              "wedding_guest",
              "party",
              "workout",
              "outdoor",
              "travel"
            ]
          },
          "weather": {
            "$ref": "#/components/schemas/Weather"
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "nl",
              "fr",
              "de",
              "es"
            ]
          },
          "use_wardrobe": {
            "type": "boolean"
          }
        }
      },
      "PreviewRequest": {
        "type": "object",
        "required": [
          "photo"
        ],
        "properties": {
          "photo": {
            "type": "string"
          }
        }
      },
      "Preview": {
        "type": "object",
        "properties": {
          "image_quality": {
            "type": "object"
          },
          "palette_hex": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "white_balanced": {
            "type": "boolean"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "thumbnail": {
            "type": "string"
          }
        }
      },
      "Accepted": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "poll": {
            "type": "string"
          }
        }
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ]
          },
          "analysis_id": {
            "type": "string"
          },
          "occasion": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AnalysisSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "occasion": {
            "type": "string"
          },
          "occasion_label": {
            "type": "string"
          },
          "overall": {
            "type": "integer"
          },
          "garments": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "palette": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "has_thumbnail": {
            "type": "boolean"
          },
          "units": {
            "type": "integer"
          }
        }
      },
      "Analysis": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "result": {
            "type": "object"
          },
          "has_thumbnail": {
            "type": "boolean"
          },
          "units": {
            "type": "integer"
          },
          "cost_eur": {
            "type": "number"
          },
          "source": {
            "type": "string"
          }
        }
      },
      "GarmentInput": {
        "type": "object",
        "required": [
          "category",
          "hex"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "attrs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hex": {
            "type": "string"
          }
        }
      },
      "ScoreRequest": {
        "type": "object",
        "required": [
          "garments",
          "occasion"
        ],
        "properties": {
          "garments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GarmentInput"
            }
          },
          "occasion": {
            "type": "string"
          },
          "weather": {
            "$ref": "#/components/schemas/Weather"
          }
        }
      },
      "ScoreResult": {
        "type": "object",
        "properties": {
          "garments": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "scores": {
            "type": "object"
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "checks_passed": {
            "type": "boolean"
          },
          "wardrobe_matches": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "History": {
        "type": "object",
        "properties": {
          "keep_history": {
            "type": "boolean"
          },
          "weekly": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "colors": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "garments": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "occasions": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "total": {
            "type": "integer"
          },
          "days": {
            "type": "integer"
          }
        }
      },
      "ItemInput": {
        "type": "object",
        "required": [
          "name",
          "category",
          "hex"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "hex": {
            "type": "string"
          },
          "attrs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Item": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "slot": {
            "type": "string"
          },
          "hex": {
            "type": "string"
          },
          "color_name": {
            "type": "string"
          },
          "color_family": {
            "type": "string"
          },
          "attrs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "formality": {
            "type": "number"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Problem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          }
        }
      }
    }
  }
}