{
  "openapi": "3.0.3",
  "info": {
    "title": "Fringue Enterprise API",
    "description": "B2B virtual try-on API. Authenticate with your `X-API-Key`.",
    "version": "1.0.0",
    "contact": {
      "email": "enterprise@fringue.app"
    }
  },
  "servers": [
    {
      "url": "/api/v1",
      "description": "Current server"
    }
  ],
  "tags": [
    {
      "name": "Partner",
      "description": "Virtual try-on endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Partner API key (format: `fre_live_...`)"
      }
    },
    "schemas": {
      "ProcessingJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "processing",
              "completed",
              "failed"
            ]
          },
          "itemName": {
            "type": "string",
            "example": "Blue Denim Jacket"
          },
          "creditsDeducted": {
            "type": "integer",
            "nullable": true,
            "example": 2
          },
          "metadata": {
            "type": "object",
            "nullable": true,
            "properties": {
              "processingTimeMs": {
                "type": "integer",
                "example": 4200
              },
              "inputTokens": {
                "type": "integer",
                "example": 1024
              },
              "outputTokens": {
                "type": "integer",
                "example": 512
              },
              "totalTokens": {
                "type": "integer",
                "example": 1536
              }
            }
          },
          "processingStartedAt": {
            "type": "string",
            "format": "date-time"
          },
          "processingCompletedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/try-on": {
      "post": {
        "tags": [
          "Partner"
        ],
        "summary": "Virtual try-on (SSE)",
        "description": "Perform a virtual try-on. Returns a **Server-Sent Events** stream with real-time progress. Save the `processing_id` from the first event — use `GET /result/{processingId}` if the connection drops.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "person_image",
                  "clothing_image",
                  "item_name"
                ],
                "properties": {
                  "person_image": {
                    "type": "string",
                    "description": "Base64-encoded person photo (JPEG/PNG/WebP, max 3MB encoded)",
                    "example": "<base64>"
                  },
                  "clothing_image": {
                    "type": "string",
                    "description": "Base64-encoded clothing photo (JPEG/PNG/WebP, max 3MB encoded)",
                    "example": "<base64>"
                  },
                  "item_name": {
                    "type": "string",
                    "description": "Name of the clothing item",
                    "example": "Blue Denim Jacket"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SSE stream (`text/event-stream`)",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Sequence of SSE events. Each line: `data: <JSON>\\n\\n`",
                  "example": "data: {\"step\":\"processing\",\"progress\":10,\"message\":\"Starting try-on...\",\"processing_id\":\"uuid\"}\ndata: {\"step\":\"generating\",\"progress\":30,\"message\":\"Generating virtual try-on...\"}\ndata: {\"step\":\"uploading\",\"progress\":80,\"message\":\"Saving result...\"}\ndata: {\"step\":\"completed\",\"progress\":100,\"processing_id\":\"uuid\",\"result_url\":\"https://...\",\"result_url_expires_at\":\"ISO\",\"credits_used\":2,\"credits_remaining\":48,\"processing_time_ms\":4200}"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Missing required field: person_image"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, revoked, or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Invalid or revoked API key"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Insufficient credits"
                }
              }
            }
          },
          "429": {
            "description": "RPM limit exceeded — includes `Retry-After` header",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Rate limit exceeded. Retry after 15 seconds."
                }
              }
            }
          }
        }
      }
    },
    "/result/{processingId}": {
      "get": {
        "tags": [
          "Partner"
        ],
        "summary": "Get try-on result",
        "description": "Retrieve status and result of a try-on job. Use as a fallback if your SSE connection dropped. Signed URL is automatically refreshed if expired.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "processingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Processing ID from the try-on SSE stream"
          }
        ],
        "responses": {
          "200": {
            "description": "Job details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "processing_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "processing",
                        "completed",
                        "failed"
                      ]
                    },
                    "result_url": {
                      "type": "string",
                      "format": "uri",
                      "nullable": true,
                      "description": "30-min signed URL (present when completed)"
                    },
                    "result_url_expires_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "error": {
                      "type": "string",
                      "nullable": true
                    },
                    "credits_deducted": {
                      "type": "integer",
                      "nullable": true
                    },
                    "metadata": {
                      "type": "object",
                      "nullable": true
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "processing_completed_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Invalid or revoked API key"
                }
              }
            }
          },
          "404": {
            "description": "Not found or belongs to another customer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Processing job not found"
                }
              }
            }
          },
          "410": {
            "description": "Job expired (older than 7 days)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Job has expired and is no longer available"
                }
              }
            }
          }
        }
      }
    }
  }
}