{
  "openapi": "3.1.0",
  "info": {
    "title": "ClearList API",
    "version": "0.3.0",
    "description": "API for the ClearList AI-powered moving sale platform. Agents authenticate via API key acquired through the email verification flow.",
    "contact": {
      "email": "hello@clearlist.me",
      "url": "https://clearlist.me"
    }
  },
  "servers": [
    {
      "url": "https://clearlist.me",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-ClearList-API-Key",
        "description": "API key in `cl_<64-hex>` format. Obtained via POST /api/auth/verify-code with `{ email, code, agent: true }`."
      },
      "bearerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Firebase ID token for web UI authentication."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/api/auth/send-code": {
      "post": {
        "summary": "Send verification code",
        "description": "Sends a 6-digit verification code to the given email address. No authentication required.",
        "security": [],
        "x-tool-id": "send_verification_code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/verify-code": {
      "post": {
        "summary": "Verify code and get API key",
        "description": "Verifies the 6-digit code. Creates account if new. Returns API key when `agent: true` is set.",
        "security": [],
        "x-tool-id": "verify_code",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "code"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "code": { "type": "string", "pattern": "^[0-9]{6}$" },
                  "agent": { "type": "boolean", "description": "Set true to receive an API key in the response." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "customToken": { "type": "string", "nullable": true },
                    "isNewUser": { "type": "boolean" },
                    "uid": { "type": "string" },
                    "apiKey": { "type": "string", "description": "Only returned when agent=true. Format: cl_<64-hex>" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/items": {
      "get": {
        "summary": "List all items",
        "description": "Returns all items for the authenticated seller.",
        "x-tool-id": "get_listings",
        "responses": {
          "200": {
            "description": "Items list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": { "type": "object" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a listing",
        "description": "Upload photos and create an AI-generated listing.",
        "x-tool-id": "create_listing",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["photos"],
                "properties": {
                  "photos": {
                    "type": "array",
                    "items": { "type": "string", "format": "uri" },
                    "maxItems": 5
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Listing created"
          }
        }
      }
    },
    "/api/pages/publish": {
      "post": {
        "summary": "Publish sale page",
        "description": "Publishes the seller's sale page with location info.",
        "x-tool-id": "publish_page",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "city": { "type": "string" },
                  "state": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Page published"
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Liveness probe",
        "description": "Zero-dependency liveness check. Always returns 200 if the process is alive.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is alive",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["ok"] },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "summary": "Dependency-aware status",
        "description": "Checks Firestore and Stripe connectivity. Returns 'ok' or 'degraded'.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["ok", "degraded"] },
                    "timestamp": { "type": "string", "format": "date-time" },
                    "version": { "type": "string" },
                    "checks": {
                      "type": "object",
                      "properties": {
                        "firestore": { "type": "boolean" },
                        "stripe": { "type": "boolean" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}