{
    "openapi": "3.1.0",
    "info": {
        "title": "Vein Directory API",
        "version": "1.0.0",
        "description": "Interactive documentation for the Vein Directory API."
    },
    "servers": [
        {
            "url": "http:\/\/veindirectoryapi.smartnoticeboard.io\/api"
        }
    ],
    "paths": {
        "\/login": {
            "post": {
                "summary": "Authenticate and retrieve an access token.",
                "tags": [
                    "Auth"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email",
                                    "password"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "example": "admin@example.com"
                                    },
                                    "password": {
                                        "type": "string",
                                        "format": "password",
                                        "example": "password"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful authentication.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/AuthTokenResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed or invalid credentials.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/register": {
            "post": {
                "summary": "Register a new user account.",
                "tags": [
                    "Auth"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name",
                                    "email",
                                    "password",
                                    "password_confirmation"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "example": "John Doe"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "example": "user@example.com"
                                    },
                                    "password": {
                                        "type": "string",
                                        "format": "password",
                                        "minLength": 8,
                                        "example": "password123"
                                    },
                                    "password_confirmation": {
                                        "type": "string",
                                        "format": "password",
                                        "example": "password123"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "User successfully registered.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/AuthTokenResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/logout": {
            "post": {
                "summary": "Revoke the current access token.",
                "tags": [
                    "Auth"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Logged out successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "Logged out successfully"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    }
                }
            }
        },
        "\/user": {
            "get": {
                "summary": "Get the authenticated user with roles and permissions.",
                "tags": [
                    "Auth"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Authenticated user retrieved.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/User"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    }
                }
            }
        },
        "\/guest\/get-cities": {
            "get": {
                "summary": "List active cities for public\/guest use.",
                "description": "Returns active cities with nested state (including state name). Cities with an active doctor are listed first. No Sanctum auth required \u2014 use the guest token via **Authorize** (`X-Guest-Token`) or the `guest_token` query parameter. When `paginate` is provided, returns a paginated response; otherwise returns all matching cities (optionally capped with `limit`). Set `is_sitemap=1` for the flat sitemap payload: only active cities that have an active doctor (`city_name`, `state_name`, `doctor_id`, `doctor_name`).",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "guest_token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "varicose-guest-api-token"
                        },
                        "description": "Alternative to the `X-Guest-Token` header."
                    },
                    {
                        "name": "paginate",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 10
                        },
                        "description": "When provided, returns paginated results with this many items per page."
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "example": 10
                        },
                        "description": "Maximum number of cities to return (used when `paginate` is not provided)."
                    },
                    {
                        "name": "is_random",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                0
                            ],
                            "example": 1
                        },
                        "description": "1 = return cities in random order, 0 = return in latest order."
                    },
                    {
                        "name": "state_id",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 1
                        },
                        "description": "Filter by state ID."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "Los"
                        },
                        "description": "Search by city name or code."
                    },
                    {
                        "name": "is_featured",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                0
                            ],
                            "example": 1
                        },
                        "description": "Filter by featured (1) or not featured (0)."
                    },
                    {
                        "name": "market_available",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                0
                            ],
                            "example": 1
                        },
                        "description": "1 = only cities without an active doctor (open partner markets). Ignored when `is_sitemap=1`."
                    },
                    {
                        "name": "is_sitemap",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                0
                            ],
                            "example": 1
                        },
                        "description": "1 = sitemap mode: returns a flat array of active cities that have an active doctor (cached 24h). Each row includes `city_name`, `state_name`, `doctor_id`, and `doctor_name`. Other list filters are ignored."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Cities retrieved successfully (standard list, paginated list, or sitemap list when `is_sitemap=1`).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "allOf": [
                                                {
                                                    "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#\/components\/schemas\/City"
                                                            }
                                                        }
                                                    }
                                                }
                                            ]
                                        },
                                        {
                                            "allOf": [
                                                {
                                                    "$ref": "#\/components\/schemas\/ApiPaginatedResponse"
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#\/components\/schemas\/City"
                                                            }
                                                        }
                                                    }
                                                }
                                            ]
                                        },
                                        {
                                            "allOf": [
                                                {
                                                    "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                                },
                                                {
                                                    "type": "object",
                                                    "properties": {
                                                        "data": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#\/components\/schemas\/SitemapCity"
                                                            }
                                                        }
                                                    }
                                                }
                                            ]
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid or missing guest token.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 401
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid guest token."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Guest API token is not configured on the server.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 503
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Guest API token is not configured."
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/guest\/get-states": {
            "get": {
                "summary": "List active states for public\/guest use.",
                "description": "Returns all active states (id, code, name) ordered by name. No Sanctum auth required \u2014 use the guest token via **Authorize** (`X-Guest-Token`) or the `guest_token` query parameter.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "guest_token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "varicose-guest-api-token"
                        },
                        "description": "Alternative to the `X-Guest-Token` header."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "States retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#\/components\/schemas\/State"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid or missing guest token."
                    }
                }
            }
        },
        "\/guest\/get-city\/{id}": {
            "get": {
                "summary": "Get a single active city for public\/guest use.",
                "description": "Returns one active city by ID with nested state and the active doctor (if any). No Sanctum auth required \u2014 use the guest token via **Authorize** (`X-Guest-Token`) or the `guest_token` query parameter.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "example": 1
                        },
                        "description": "City ID"
                    },
                    {
                        "name": "guest_token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "varicose-guest-api-token"
                        },
                        "description": "Alternative to the `X-Guest-Token` header."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "City retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/GuestCityDetail"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid or missing guest token.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 401
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid guest token."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "City not found or inactive.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "example": "No query results for model [App\\Models\\City]."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Guest API token is not configured on the server.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 503
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Guest API token is not configured."
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/guest\/get-page": {
            "get": {
                "summary": "Get a landing page by URL slug.",
                "description": "Returns a single page record by its public URL path (slug). Leading and trailing slashes are stripped before lookup. No Sanctum auth required \u2014 use the guest token via **Authorize** (`X-Guest-Token`) or the `guest_token` query parameter.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "url",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "miami-varicose-vein-treatment"
                        },
                        "description": "Public URL slug (path segment after the site root)."
                    },
                    {
                        "name": "guest_token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "varicose-guest-api-token"
                        },
                        "description": "Alternative to the `X-Guest-Token` header."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Page retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/Page"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid or missing guest token.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 401
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid guest token."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Page not found.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 404
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Page not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed (missing or invalid `url`).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests."
                    },
                    "503": {
                        "description": "Guest API token is not configured on the server.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 503
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Guest API token is not configured."
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/guest\/get-survey\/{id}": {
            "get": {
                "summary": "Get a survey submission by ID.",
                "description": "Returns a single survey record for public guest use. When `page_type=thank_you` is provided, the response also includes `state_name`, `city_name`, and the linked landing `page` record (via `page_id`). No Sanctum auth required \u2014 use the guest token via **Authorize** (`X-Guest-Token`) or the `guest_token` query parameter.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "example": 15
                        },
                        "description": "Survey ID."
                    },
                    {
                        "name": "page_type",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "thank_you"
                            ],
                            "example": "thank_you"
                        },
                        "description": "When set to `thank_you`, includes `state_name`, `city_name`, and linked `page` details."
                    },
                    {
                        "name": "guest_token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "varicose-guest-api-token"
                        },
                        "description": "Alternative to the `X-Guest-Token` header."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Survey retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#\/components\/schemas\/GuestSurvey"
                                                        },
                                                        {
                                                            "$ref": "#\/components\/schemas\/GuestSurveyThankYou"
                                                        }
                                                    ]
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid or missing guest token.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 401
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid guest token."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Survey not found.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 404
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Survey not found."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation failed (invalid `page_type`).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests."
                    },
                    "503": {
                        "description": "Guest API token is not configured on the server.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 503
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Guest API token is not configured."
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/guest\/directory-leads": {
            "post": {
                "summary": "Submit a homepage directory lead.",
                "description": "Creates an unassigned consultation lead from the homepage form (ZIP-based matching handled by admin). Requires guest token.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "full_name",
                                    "phone",
                                    "zip",
                                    "email",
                                    "symptoms",
                                    "duration",
                                    "timing"
                                ],
                                "properties": {
                                    "full_name": {
                                        "type": "string",
                                        "example": "Jane Doe"
                                    },
                                    "phone": {
                                        "type": "string",
                                        "example": "(305) 555-0100"
                                    },
                                    "zip": {
                                        "type": "string",
                                        "example": "33139"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "symptoms": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "duration": {
                                        "type": "string",
                                        "example": "6mo \u2013 2 yrs"
                                    },
                                    "timing": {
                                        "type": "string",
                                        "example": "Within a week"
                                    },
                                    "website": {
                                        "type": "string",
                                        "description": "Honeypot \u2014 must be empty"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Directory lead created."
                    },
                    "401": {
                        "description": "Invalid or missing guest token."
                    },
                    "422": {
                        "description": "Validation failed."
                    },
                    "429": {
                        "description": "Too many requests."
                    }
                }
            }
        },
        "\/guest\/consultation-requests": {
            "post": {
                "summary": "Submit a city partner consultation request.",
                "description": "Creates a consultation lead for an active city with an active doctor. Requires guest token.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "city_id",
                                    "full_name",
                                    "phone",
                                    "zip",
                                    "email",
                                    "main_concern"
                                ],
                                "properties": {
                                    "city_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "full_name": {
                                        "type": "string",
                                        "example": "Jane Doe"
                                    },
                                    "phone": {
                                        "type": "string",
                                        "example": "(305) 555-0100"
                                    },
                                    "zip": {
                                        "type": "string",
                                        "example": "33139"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "main_concern": {
                                        "type": "string",
                                        "example": "Swelling"
                                    },
                                    "message": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "website": {
                                        "type": "string",
                                        "description": "Honeypot \u2014 must be empty"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Consultation request created."
                    },
                    "401": {
                        "description": "Invalid or missing guest token."
                    },
                    "422": {
                        "description": "Validation failed or city unavailable."
                    },
                    "429": {
                        "description": "Too many requests."
                    }
                }
            }
        },
        "\/guest\/partner-applications": {
            "post": {
                "summary": "Submit a partner market application.",
                "description": "Creates a partner application for an open market. Rejects cities that already have an active doctor. Requires guest token.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "doctor_name",
                                    "practice_name",
                                    "email",
                                    "phone",
                                    "description"
                                ],
                                "properties": {
                                    "city_id": {
                                        "type": "integer",
                                        "nullable": true,
                                        "example": 1
                                    },
                                    "state_id": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "doctor_name": {
                                        "type": "string",
                                        "example": "Dr. Jane Smith"
                                    },
                                    "practice_name": {
                                        "type": "string",
                                        "example": "City Vein Center"
                                    },
                                    "city_name": {
                                        "type": "string",
                                        "nullable": true,
                                        "example": "Charlotte"
                                    },
                                    "state_name": {
                                        "type": "string",
                                        "nullable": true,
                                        "example": "North Carolina"
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "phone": {
                                        "type": "string",
                                        "example": "(704) 555-0100"
                                    },
                                    "description": {
                                        "type": "string"
                                    },
                                    "website": {
                                        "type": "string",
                                        "description": "Honeypot \u2014 must be empty"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Partner application created."
                    },
                    "401": {
                        "description": "Invalid or missing guest token."
                    },
                    "422": {
                        "description": "Validation failed or market unavailable."
                    },
                    "429": {
                        "description": "Too many requests."
                    }
                }
            }
        },
        "\/guest\/directory-faqs": {
            "get": {
                "summary": "List active directory FAQs for public\/guest use.",
                "description": "Returns all active directory FAQs with nested directory detail (id, name). No Sanctum auth required \u2014 use the guest token via **Authorize** (`X-Guest-Token`) or the `guest_token` query parameter.",
                "tags": [
                    "Guest"
                ],
                "security": [
                    {
                        "guestAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "guest_token",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "varicose-guest-api-token"
                        },
                        "description": "Alternative to the `X-Guest-Token` header."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Directory FAQs retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#\/components\/schemas\/DirectoryFaq"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid or missing guest token.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 401
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Invalid guest token."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Guest API token is not configured on the server.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status_code": {
                                            "type": "integer",
                                            "example": 503
                                        },
                                        "message": {
                                            "type": "string",
                                            "example": "Guest API token is not configured."
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/states": {
            "get": {
                "summary": "List all states.",
                "tags": [
                    "States"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "paginate",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 10
                        },
                        "description": "When provided, returns paginated results."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                0
                            ],
                            "example": 1
                        },
                        "description": "Filter by active (1) or inactive (0) status."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "States retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "$ref": "#\/components\/schemas\/ApiPaginatedResponse"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires read-state)."
                    }
                }
            },
            "post": {
                "summary": "Create a new state.",
                "tags": [
                    "States"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart\/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "code",
                                    "name",
                                    "status",
                                    "image"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 10,
                                        "example": "CA"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "example": "California"
                                    },
                                    "status": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = active, 0 = inactive"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "State image (jpeg, png, jpg, gif, webp). Max 2MB."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "State created successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/State"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires create-state)."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/states\/{state}": {
            "get": {
                "summary": "Get a single state.",
                "tags": [
                    "States"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "state",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "State ID"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "State retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/State"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires read-state)."
                    },
                    "404": {
                        "description": "State not found."
                    }
                }
            },
            "put": {
                "summary": "Update a state.",
                "tags": [
                    "States"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "state",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "State ID"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart\/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "code",
                                    "name",
                                    "status"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 10,
                                        "example": "CA"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "example": "California"
                                    },
                                    "status": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = active, 0 = inactive"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "State image (jpeg, png, jpg, gif, webp). Max 2MB."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "State updated successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/State"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires edit-state)."
                    },
                    "404": {
                        "description": "State not found."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "patch": {
                "summary": "Partially update a state.",
                "tags": [
                    "States"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "state",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "State ID"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart\/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "code",
                                    "name",
                                    "status"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 10,
                                        "example": "CA"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "example": "California"
                                    },
                                    "status": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = active, 0 = inactive"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "State image (jpeg, png, jpg, gif, webp). Max 2MB."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "State updated successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/State"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires edit-state)."
                    },
                    "404": {
                        "description": "State not found."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "summary": "Delete a state.",
                "tags": [
                    "States"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "state",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "State ID"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "State deleted successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ApiMessageResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires delete-state)."
                    },
                    "404": {
                        "description": "State not found."
                    }
                }
            }
        },
        "\/cities": {
            "get": {
                "summary": "List all cities.",
                "tags": [
                    "Cities"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "paginate",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 10
                        },
                        "description": "When provided, returns paginated results."
                    },
                    {
                        "name": "state_id",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 1
                        },
                        "description": "Filter by state ID."
                    },
                    {
                        "name": "is_featured",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                0
                            ],
                            "example": 1
                        },
                        "description": "Filter by featured (1) or not featured (0)."
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                0
                            ],
                            "example": 1
                        },
                        "description": "Filter by active (1) or inactive (0) status."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "Los"
                        },
                        "description": "Search by city name or code."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Cities retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "$ref": "#\/components\/schemas\/ApiPaginatedResponse"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires read-city)."
                    }
                }
            },
            "post": {
                "summary": "Create a new city.",
                "tags": [
                    "Cities"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart\/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "code",
                                    "name",
                                    "state_id",
                                    "is_featured",
                                    "status",
                                    "image"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "example": "LAX"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "example": "Los Angeles"
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "example": "City in California"
                                    },
                                    "state_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "description": "Required. ID of the parent state."
                                    },
                                    "is_featured": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = featured, 0 = not featured"
                                    },
                                    "status": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = active, 0 = inactive"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "City image (jpeg, png, jpg, gif, webp). Max 2MB."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "City created successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/City"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires create-city)."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/cities\/{city}": {
            "get": {
                "summary": "Get a single city.",
                "tags": [
                    "Cities"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City ID"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "City retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/City"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires read-city)."
                    },
                    "404": {
                        "description": "City not found."
                    }
                }
            },
            "put": {
                "summary": "Update a city.",
                "tags": [
                    "Cities"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City ID"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart\/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "code",
                                    "name",
                                    "state_id",
                                    "is_featured",
                                    "status"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "example": "LAX"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "example": "Los Angeles"
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "example": "City in California"
                                    },
                                    "state_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "description": "Required. ID of the parent state."
                                    },
                                    "is_featured": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = featured, 0 = not featured"
                                    },
                                    "status": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = active, 0 = inactive"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "City image (jpeg, png, jpg, gif, webp). Max 2MB."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "City updated successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/City"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires edit-city)."
                    },
                    "404": {
                        "description": "City not found."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "patch": {
                "summary": "Partially update a city.",
                "tags": [
                    "Cities"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City ID"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart\/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "code",
                                    "name",
                                    "state_id",
                                    "is_featured",
                                    "status"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "maxLength": 20,
                                        "example": "LAX"
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "example": "Los Angeles"
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "example": "City in California"
                                    },
                                    "state_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "description": "Required. ID of the parent state."
                                    },
                                    "is_featured": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = featured, 0 = not featured"
                                    },
                                    "status": {
                                        "type": "integer",
                                        "enum": [
                                            1,
                                            0
                                        ],
                                        "example": 1,
                                        "description": "1 = active, 0 = inactive"
                                    },
                                    "image": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "City image (jpeg, png, jpg, gif, webp). Max 2MB."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "City updated successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/City"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires edit-city)."
                    },
                    "404": {
                        "description": "City not found."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "summary": "Delete a city.",
                "tags": [
                    "Cities"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City ID"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "City deleted successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ApiMessageResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "403": {
                        "description": "Insufficient permissions (requires delete-city)."
                    },
                    "404": {
                        "description": "City not found."
                    }
                }
            }
        },
        "\/city-reviews": {
            "get": {
                "summary": "List all city reviews.",
                "tags": [
                    "City Reviews"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "paginate",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 10
                        },
                        "description": "When provided, returns paginated results."
                    },
                    {
                        "name": "city_id",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 1
                        },
                        "description": "Filter by city ID."
                    },
                    {
                        "name": "rating",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 5,
                            "example": 5
                        },
                        "description": "Filter by star rating."
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "Maria"
                        },
                        "description": "Search reviewer name, location, procedure, or review text."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "City reviews retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "$ref": "#\/components\/schemas\/ApiPaginatedResponse"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    }
                }
            },
            "post": {
                "summary": "Create a new city review.",
                "tags": [
                    "City Reviews"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "city_id",
                                    "rating",
                                    "review_text",
                                    "reviewer_name",
                                    "location",
                                    "procedure"
                                ],
                                "properties": {
                                    "city_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "description": "Required. ID of the city this review belongs to."
                                    },
                                    "rating": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 5,
                                        "example": 5
                                    },
                                    "review_text": {
                                        "type": "string",
                                        "example": "Excellent care and results. Highly recommend."
                                    },
                                    "reviewer_name": {
                                        "type": "string",
                                        "example": "Maria L."
                                    },
                                    "reviewer_age": {
                                        "type": "integer",
                                        "nullable": true,
                                        "example": 54
                                    },
                                    "location": {
                                        "type": "string",
                                        "example": "Brickell"
                                    },
                                    "procedure": {
                                        "type": "string",
                                        "example": "RFA"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "City review created successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/CityReview"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/city-reviews\/{city_review}": {
            "get": {
                "summary": "Get a single city review.",
                "tags": [
                    "City Reviews"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city_review",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City review ID"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "City review retrieved successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/CityReview"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "404": {
                        "description": "City review not found."
                    }
                }
            },
            "put": {
                "summary": "Update a city review.",
                "tags": [
                    "City Reviews"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city_review",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City review ID"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "city_id",
                                    "rating",
                                    "review_text",
                                    "reviewer_name",
                                    "location",
                                    "procedure"
                                ],
                                "properties": {
                                    "city_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "description": "Required. ID of the city this review belongs to."
                                    },
                                    "rating": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 5,
                                        "example": 5
                                    },
                                    "review_text": {
                                        "type": "string",
                                        "example": "Excellent care and results. Highly recommend."
                                    },
                                    "reviewer_name": {
                                        "type": "string",
                                        "example": "Maria L."
                                    },
                                    "reviewer_age": {
                                        "type": "integer",
                                        "nullable": true,
                                        "example": 54
                                    },
                                    "location": {
                                        "type": "string",
                                        "example": "Brickell"
                                    },
                                    "procedure": {
                                        "type": "string",
                                        "example": "RFA"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "City review updated successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/CityReview"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "404": {
                        "description": "City review not found."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "patch": {
                "summary": "Partially update a city review.",
                "tags": [
                    "City Reviews"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city_review",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City review ID"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application\/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "city_id",
                                    "rating",
                                    "review_text",
                                    "reviewer_name",
                                    "location",
                                    "procedure"
                                ],
                                "properties": {
                                    "city_id": {
                                        "type": "integer",
                                        "example": 1,
                                        "description": "Required. ID of the city this review belongs to."
                                    },
                                    "rating": {
                                        "type": "integer",
                                        "minimum": 1,
                                        "maximum": 5,
                                        "example": 5
                                    },
                                    "review_text": {
                                        "type": "string",
                                        "example": "Excellent care and results. Highly recommend."
                                    },
                                    "reviewer_name": {
                                        "type": "string",
                                        "example": "Maria L."
                                    },
                                    "reviewer_age": {
                                        "type": "integer",
                                        "nullable": true,
                                        "example": 54
                                    },
                                    "location": {
                                        "type": "string",
                                        "example": "Brickell"
                                    },
                                    "procedure": {
                                        "type": "string",
                                        "example": "RFA"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "City review updated successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#\/components\/schemas\/ApiSuccessResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "$ref": "#\/components\/schemas\/CityReview"
                                                }
                                            }
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "404": {
                        "description": "City review not found."
                    },
                    "422": {
                        "description": "Validation failed.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ValidationErrorResponse"
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "summary": "Delete a city review.",
                "tags": [
                    "City Reviews"
                ],
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "city_review",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        },
                        "description": "City review ID"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "City review deleted successfully.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/ApiMessageResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Unauthenticated."
                    },
                    "404": {
                        "description": "City review not found."
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "Sanctum",
                "description": "Enter the token from login\/register (e.g. `1|abcdef...`)."
            },
            "guestAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Guest-Token",
                "description": "Static guest API token from `GUEST_API_TOKEN` in `.env` (e.g. `varicose-guest-api-token`)."
            }
        },
        "schemas": {
            "ApiSuccessResponse": {
                "type": "object",
                "properties": {
                    "status_code": {
                        "type": "integer",
                        "example": 200
                    },
                    "message": {
                        "type": "string",
                        "example": "Success message"
                    },
                    "data": {
                        "type": "object"
                    }
                }
            },
            "ApiPaginatedResponse": {
                "type": "object",
                "properties": {
                    "status_code": {
                        "type": "integer",
                        "example": 200
                    },
                    "message": {
                        "type": "string",
                        "example": "Records retrieved successfully."
                    },
                    "current_page": {
                        "type": "integer",
                        "example": 1
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#\/components\/schemas\/State"
                        }
                    },
                    "total": {
                        "type": "integer",
                        "example": 50
                    },
                    "per_page": {
                        "type": "integer",
                        "example": 10
                    }
                }
            },
            "ApiMessageResponse": {
                "type": "object",
                "properties": {
                    "status_code": {
                        "type": "integer",
                        "example": 200
                    },
                    "message": {
                        "type": "string",
                        "example": "Operation completed successfully."
                    }
                }
            },
            "ValidationErrorResponse": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string",
                        "example": "The given data was invalid."
                    },
                    "errors": {
                        "type": "object"
                    }
                }
            },
            "User": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Admin User"
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "admin@example.com"
                    },
                    "role": {
                        "type": "string",
                        "example": "admin"
                    },
                    "roles": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "name": {
                                    "type": "string",
                                    "example": "admin"
                                }
                            }
                        }
                    },
                    "permissions": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "name": {
                                    "type": "string",
                                    "example": "read-state"
                                }
                            }
                        }
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "State": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "code": {
                        "type": "string",
                        "example": "CA"
                    },
                    "name": {
                        "type": "string",
                        "example": "California"
                    },
                    "status": {
                        "type": "integer",
                        "enum": [
                            1,
                            0
                        ],
                        "example": 1,
                        "description": "1 = active, 0 = inactive"
                    },
                    "image": {
                        "type": "string",
                        "nullable": true,
                        "example": "states\/example.jpg"
                    },
                    "image_url": {
                        "type": "string",
                        "nullable": true,
                        "example": "http:\/\/localhost\/storage\/states\/example.jpg"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "City": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "code": {
                        "type": "string",
                        "example": "LAX"
                    },
                    "name": {
                        "type": "string",
                        "example": "Los Angeles"
                    },
                    "description": {
                        "type": "string",
                        "nullable": true,
                        "example": "City in California"
                    },
                    "state_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "is_featured": {
                        "type": "integer",
                        "enum": [
                            1,
                            0
                        ],
                        "example": 1,
                        "description": "1 = featured, 0 = not featured"
                    },
                    "status": {
                        "type": "integer",
                        "enum": [
                            1,
                            0
                        ],
                        "example": 1,
                        "description": "1 = active, 0 = inactive"
                    },
                    "image": {
                        "type": "string",
                        "nullable": true,
                        "example": "cities\/example.jpg"
                    },
                    "image_url": {
                        "type": "string",
                        "nullable": true,
                        "example": "http:\/\/localhost\/storage\/cities\/example.jpg"
                    },
                    "added_by": {
                        "type": "integer",
                        "example": 1
                    },
                    "state": {
                        "$ref": "#\/components\/schemas\/State"
                    },
                    "added_by_user": {
                        "$ref": "#\/components\/schemas\/User"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "SitemapCity": {
                "type": "object",
                "description": "Flat city row returned when `is_sitemap=1` (optimized for sitemap generation).",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "city_name": {
                        "type": "string",
                        "example": "Birmingham"
                    },
                    "state_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "state_name": {
                        "type": "string",
                        "example": "Alabama"
                    },
                    "doctor_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 5
                    },
                    "doctor_name": {
                        "type": "string",
                        "nullable": true,
                        "example": "Dr. Jane Smith"
                    }
                }
            },
            "Doctor": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "city_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "full_name": {
                        "type": "string",
                        "example": "Dr. Elena Marquez"
                    },
                    "practice_name": {
                        "type": "string",
                        "example": "Miami Vein Center"
                    },
                    "credentials": {
                        "type": "string",
                        "example": "MD, RPVI"
                    },
                    "tagline": {
                        "type": "string",
                        "example": "Board-certified vein specialist"
                    },
                    "bio": {
                        "type": "string",
                        "example": "Full biography..."
                    },
                    "phone": {
                        "type": "string",
                        "example": "(305) 555-0100"
                    },
                    "address": {
                        "type": "string",
                        "example": "123 Brickell Ave, Miami, FL"
                    },
                    "experience": {
                        "type": "string",
                        "example": "15+ years"
                    },
                    "market_experience": {
                        "type": "string",
                        "example": "Serving South Florida since 2010"
                    },
                    "procedures": {
                        "type": "array",
                        "description": "Legacy; always empty. Use treatments relation.",
                        "items": {
                            "type": "string"
                        },
                        "example": []
                    },
                    "treatments": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "slug": {
                                    "type": "string"
                                },
                                "title": {
                                    "type": "string"
                                },
                                "short": {
                                    "type": "string"
                                },
                                "duration": {
                                    "type": "string"
                                },
                                "recovery": {
                                    "type": "string"
                                },
                                "insurance": {
                                    "type": "string"
                                },
                                "sort_order": {
                                    "type": "integer"
                                }
                            }
                        }
                    },
                    "accepted_insurances": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "Medicare",
                            "Aetna"
                        ]
                    },
                    "avatar_path": {
                        "type": "string",
                        "nullable": true
                    },
                    "avatar_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "integer",
                        "enum": [
                            1,
                            0
                        ],
                        "example": 1
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "DirectoryDetail": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "name": {
                        "type": "string",
                        "example": "Varicose MD Directory"
                    }
                }
            },
            "DirectoryFaq": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "directory_detail_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "question": {
                        "type": "string",
                        "example": "What is varicose vein treatment?"
                    },
                    "answer": {
                        "type": "string",
                        "example": "Modern treatments are minimally invasive and performed in-office."
                    },
                    "reviewed_by": {
                        "type": "string",
                        "example": "Dr. Jane Smith, MD"
                    },
                    "status": {
                        "type": "boolean",
                        "example": true
                    },
                    "directory_detail": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#\/components\/schemas\/DirectoryDetail"
                            }
                        ]
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "GuestCityDetail": {
                "allOf": [
                    {
                        "$ref": "#\/components\/schemas\/City"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "active_doctor": {
                                "nullable": true,
                                "allOf": [
                                    {
                                        "$ref": "#\/components\/schemas\/Doctor"
                                    }
                                ]
                            }
                        }
                    }
                ]
            },
            "CityReview": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "city_id": {
                        "type": "integer",
                        "example": 1
                    },
                    "rating": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 5,
                        "example": 5
                    },
                    "review_text": {
                        "type": "string",
                        "example": "Excellent care and results."
                    },
                    "reviewer_name": {
                        "type": "string",
                        "example": "Maria L."
                    },
                    "reviewer_age": {
                        "type": "integer",
                        "nullable": true,
                        "example": 54
                    },
                    "location": {
                        "type": "string",
                        "example": "Brickell"
                    },
                    "procedure": {
                        "type": "string",
                        "example": "RFA"
                    },
                    "added_by": {
                        "type": "integer",
                        "example": 1
                    },
                    "city": {
                        "$ref": "#\/components\/schemas\/City"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "Page": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "url": {
                        "type": "string",
                        "example": "miami-varicose-vein-treatment"
                    },
                    "city": {
                        "type": "string",
                        "nullable": true,
                        "example": "Miami"
                    },
                    "state": {
                        "type": "string",
                        "nullable": true,
                        "example": "Florida"
                    },
                    "language": {
                        "type": "string",
                        "enum": [
                            "en",
                            "es"
                        ],
                        "example": "en"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "GuestPageDetail": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 1
                    },
                    "url": {
                        "type": "string",
                        "example": "miami-varicose-vein-treatment"
                    },
                    "city": {
                        "type": "string",
                        "nullable": true,
                        "example": "Miami"
                    },
                    "state": {
                        "type": "string",
                        "nullable": true,
                        "example": "Florida"
                    },
                    "state_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 10
                    },
                    "city_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 42
                    },
                    "address": {
                        "type": "string",
                        "nullable": true,
                        "example": "123 Main St"
                    },
                    "phone": {
                        "type": "string",
                        "nullable": true,
                        "example": "(305) 555-0100"
                    },
                    "map_address": {
                        "type": "string",
                        "nullable": true
                    },
                    "language": {
                        "type": "string",
                        "enum": [
                            "en",
                            "es"
                        ],
                        "example": "en"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "GuestSurvey": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 15
                    },
                    "language": {
                        "type": "string",
                        "enum": [
                            "en",
                            "es"
                        ],
                        "example": "en"
                    },
                    "state_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 10
                    },
                    "city_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 42
                    },
                    "page_id": {
                        "type": "integer",
                        "nullable": true,
                        "example": 1
                    },
                    "first_name": {
                        "type": "string",
                        "example": "Jane"
                    },
                    "last_name": {
                        "type": "string",
                        "example": "Smith"
                    },
                    "phone": {
                        "type": "string",
                        "example": "(305) 555-0100"
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "jane@example.com"
                    },
                    "phone_country": {
                        "type": "string",
                        "nullable": true,
                        "example": "US"
                    },
                    "data": {
                        "type": "object",
                        "additionalProperties": true,
                        "example": {
                            "legSymptoms": "Often",
                            "insuranceProvider": "Medicare"
                        }
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "new",
                            "reviewed",
                            "archived"
                        ],
                        "example": "new"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "GuestSurveyThankYou": {
                "allOf": [
                    {
                        "$ref": "#\/components\/schemas\/GuestSurvey"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "state_name": {
                                "type": "string",
                                "nullable": true,
                                "example": "Florida"
                            },
                            "city_name": {
                                "type": "string",
                                "nullable": true,
                                "example": "Miami"
                            },
                            "page": {
                                "nullable": true,
                                "allOf": [
                                    {
                                        "$ref": "#\/components\/schemas\/GuestPageDetail"
                                    }
                                ]
                            }
                        }
                    }
                ]
            },
            "AuthTokenResponse": {
                "type": "object",
                "properties": {
                    "user": {
                        "$ref": "#\/components\/schemas\/User"
                    },
                    "token": {
                        "type": "string",
                        "example": "1|abcdef123456..."
                    }
                }
            }
        }
    }
}