{
    "openapi": "3.0.0",
    "info": {
        "title": "grades.com",
        "description": "API for backend <https://app.grades.com>.\n\nBoolean query parameters take `true`, `false`, `1` or `0`, in any case.",
        "termsOfService": "https://www.grades.com/terms",
        "contact": {
            "name": "Grades.com support",
            "url": "https://www.grades.com/developers",
            "email": "support@grades.com"
        },
        "version": "3.142.0"
    },
    "servers": [
        {
            "url": "https://app.grades.com/api",
            "description": "Production"
        }
    ],
    "paths": {
        "/company/{company}/review/{review}/generate-reply": {
            "post": {
                "tags": [
                    "AIReply"
                ],
                "summary": "Generate AI reply",
                "description": "Generate an AI-suggested reply for a review based on the company AI Settings context and the review content.",
                "operationId": "generateAiReply",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/GenerateAIReply"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/AIReplyForbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "422": {
                        "$ref": "#/components/responses/AISettingsIncomplete"
                    },
                    "429": {
                        "$ref": "#/components/responses/AIReplyLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    },
                    "502": {
                        "$ref": "#/components/responses/GeminiApiError"
                    },
                    "503": {
                        "$ref": "#/components/responses/AIReplyServiceBusy"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/company/{company}/agent/backtests": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "List review agent test runs",
                "description": "The business's latest test runs (without their reviews) and what is left of today's budget.",
                "operationId": "listAgentBacktests",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/AgentBacktest"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Start a review agent test run",
                "description": "Queues a test run over the last `limit` reviews (default 20, at most 50), with `settings` (the agent settings body of `PUT .../agent/settings`, not saved) or the saved settings. Answers 202; poll `GET .../agent/backtests/{backtest}`. 429 `backtest_budget` (3 runs a day by default, with Retry-After), 409 `backtest_running` / `backtest_no_reviews`.",
                "operationId": "createAgentBacktest",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "limit": {
                                        "type": "integer",
                                        "default": 20,
                                        "maximum": 50,
                                        "minimum": 1
                                    },
                                    "settings": {
                                        "type": "object",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/AgentBacktest"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/agent/backtests/{backtest}": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "Get a review agent test run",
                "description": "One test run with each review: what was replied (`replied`: on the site, in Grades.com, or none) and what the agent would have written (`agent`: decision, draft, checks, report). Kept 30 days.",
                "operationId": "getAgentBacktest",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/AgentBacktest"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "backtest",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/company/{company}/agent/settings": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "Get review agent settings",
                "description": "Dashboard session version of `GET /v1/companies/{company}/agent/settings`.",
                "operationId": "getAgentSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentSettings"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Agent"
                ],
                "summary": "Update review agent settings",
                "description": "Dashboard session version of `PUT /v1/companies/{company}/agent/settings`.",
                "operationId": "updateAgentSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1AgentSettingsUpdate"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentSettings"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/agent/actions": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "List review agent actions",
                "description": "Dashboard session version of `GET /v1/companies/{company}/agent/actions` (same query parameters).",
                "operationId": "listAgentActions",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AgentAction"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/agent/actions/{action}": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "Get a review agent action",
                "description": "Dashboard session version of `GET /v1/companies/{company}/agent/actions/{action}`.",
                "operationId": "getAgentAction",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                }
            ]
        },
        "/company/{company}/agent/actions/{action}/approve": {
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Approve a review agent action",
                "description": "Dashboard session version of `POST /v1/companies/{company}/agent/actions/{action}/approve`.",
                "operationId": "approveAgentAction",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "text": {
                                        "description": "Edited reply (max 4000) or report text (max 5000).",
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                }
            ]
        },
        "/company/{company}/agent/actions/{action}/reject": {
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Reject a review agent action",
                "description": "Dashboard session version of `POST /v1/companies/{company}/agent/actions/{action}/reject`.",
                "operationId": "rejectAgentAction",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 1000
                                    },
                                    "reason_code": {
                                        "description": "Why, as a category the agent learns from.",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "wrong_tone",
                                            "too_long",
                                            "too_short",
                                            "inaccurate",
                                            "too_generic",
                                            "wrong_language",
                                            "should_not_reply",
                                            "other"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                }
            ]
        },
        "/company/{company}/agent/triage": {
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Run the review agent now",
                "description": "Dashboard session version of `POST /v1/companies/{company}/agent/triage`.",
                "operationId": "runAgentTriage",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentTriageResult"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/agent/learnings": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "What the review agent learned",
                "description": "Dashboard session version of `GET /v1/companies/{company}/agent/learnings`.",
                "operationId": "getAgentLearnings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLearnings"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/agent/learnings/{learning}/accept": {
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Accept a learning",
                "description": "Dashboard session version of `POST /v1/companies/{company}/agent/learnings/{learning}/accept`.",
                "operationId": "acceptAgentLearning",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLearningDecision"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentLearningPath"
                }
            ]
        },
        "/company/{company}/agent/learnings/{learning}/dismiss": {
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Dismiss a learning",
                "description": "Dashboard session version of `POST /v1/companies/{company}/agent/learnings/{learning}/dismiss`.",
                "operationId": "dismissAgentLearning",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLearningDecision"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentLearningPath"
                }
            ]
        },
        "/company/{company}/agent/outcomes/summary": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "Review agent improvement",
                "description": "Dashboard session version of `GET /v1/companies/{company}/agent/outcomes/summary`.",
                "operationId": "getAgentOutcomeSummary",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "business": {
                                                    "$ref": "#/components/schemas/V1AgentOutcomeSummary"
                                                },
                                                "fleet": {
                                                    "$ref": "#/components/schemas/V1AgentOutcomeSummary"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/agent/actions/{action}/filed": {
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Mark a removal report as filed",
                "description": "Dashboard session version of `POST /v1/companies/{company}/agent/actions/{action}/filed`.",
                "operationId": "agentActionFiled",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "filed_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true
                                    },
                                    "external_reference": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 255
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                }
            ]
        },
        "/company/{company}/agent/settings/preview-voice": {
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Preview a reply voice",
                "description": "Dashboard session version of `POST /v1/companies/{company}/agent/settings/preview-voice`.",
                "operationId": "previewAgentVoice",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "reply_voice": {
                                        "properties": {
                                            "preset": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "custom": {
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 600
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    },
                                    "reply_signature": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 120
                                    },
                                    "sample": {
                                        "type": "string",
                                        "default": "positive",
                                        "enum": [
                                            "positive",
                                            "negative"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentVoicePreview"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/agent/login-requests": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "Sites waiting for a login",
                "description": "Dashboard session version of `GET /v1/companies/{company}/agent/login-requests`.",
                "operationId": "getAgentLoginRequests",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/user/api-keys": {
            "get": {
                "tags": [
                    "ApiKey"
                ],
                "summary": "List API keys",
                "description": "Lists the signed-in user's API keys (never the secret itself). `meta.scopes` lists every scope a key can carry with its plain-English sentence (the \"This key can\" lines of the dashboard).",
                "operationId": "listApiKeys",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/ApiKey"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "scopes": {
                                                    "type": "array",
                                                    "items": {
                                                        "properties": {
                                                            "scope": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "reviews:read",
                                                                    "reviews:write",
                                                                    "companies:read",
                                                                    "companies:write",
                                                                    "directory:read"
                                                                ]
                                                            },
                                                            "sentence": {
                                                                "type": "string"
                                                            },
                                                            "default": {
                                                                "type": "boolean"
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "ApiKey"
                ],
                "summary": "Create API key",
                "description": "Creates a secret API key (`gk_live_...`) for the REST API. The key is returned once, in this response only. Abilities default to read-only (`reviews:read companies:read`).",
                "operationId": "createApiKey",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "Zapier",
                                        "maxLength": 100
                                    },
                                    "abilities": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "reviews:read",
                                                "reviews:write",
                                                "companies:read",
                                                "companies:write",
                                                "directory:read"
                                            ]
                                        },
                                        "example": [
                                            "reviews:read",
                                            "companies:read"
                                        ],
                                        "minItems": 1
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "companies": {
                                        "description": "Uuids of the businesses the key is limited to (omitted or empty: every business).",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "nullable": true
                                    },
                                    "url_key": {
                                        "description": "A reporting URL key (only with integration `reporting`; scope `reviews:read` only; prefix `gk_live_url_`): the only kind of key the reports API accepts as `?key=`. Cannot be changed later.",
                                        "type": "boolean"
                                    },
                                    "integration": {
                                        "description": "Which integration the key is for (a label for the key lists; it grants nothing).",
                                        "type": "string",
                                        "example": "zapier",
                                        "nullable": true,
                                        "enum": [
                                            "zapier",
                                            "make",
                                            "n8n",
                                            "sheets",
                                            "looker",
                                            "woocommerce",
                                            "reporting"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/CreatedApiKey"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/user/api-keys/{apiKey}": {
            "delete": {
                "tags": [
                    "ApiKey"
                ],
                "summary": "Revoke API key",
                "description": "Revokes (deletes) an API key. Requests using it fail immediately.",
                "operationId": "revokeApiKey",
                "responses": {
                    "204": {
                        "description": "Revoked"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/ResourceNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "name": "apiKey",
                    "in": "path",
                    "description": "API key id.",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/company/{company}/assistant/messages": {
            "post": {
                "tags": [
                    "Assistant"
                ],
                "summary": "Ask the assistant",
                "description": "A new question (`message`, optionally in `conversation_id`), or the decision on an action that waits (`conversation_id`, `confirm_tool_call_id`, `decision` confirm | decline). Answers with server-sent events (text/event-stream). 402 `plan_upgrade_required` when the month's questions are used up, 409 `conversation_full` / `nothing_to_confirm`, 429 over 20 messages a minute, 503 `assistant_disabled` / `assistant_budget_exhausted`.",
                "operationId": "postAssistantMessage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "message": {
                                        "type": "string",
                                        "maxLength": 4000
                                    },
                                    "conversation_id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "confirm_tool_call_id": {
                                        "type": "string"
                                    },
                                    "decision": {
                                        "type": "string",
                                        "enum": [
                                            "confirm",
                                            "decline"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Server-sent events: `event: <name>` + `data: <one line of JSON>` for `conversation`, `question`, `text`, `tool`, `confirm`, `error` and `done`.",
                        "content": {
                            "text/event-stream": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/assistant/conversations": {
            "get": {
                "tags": [
                    "Assistant"
                ],
                "summary": "List assistant conversations",
                "description": "The signed-in user's newest 30 conversations with the assistant for this company, newest first, and the questions left this month (`meta.usage`).",
                "operationId": "listAssistantConversations",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/AssistantConversationSummary"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/AssistantMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/assistant/conversations/{conversation}": {
            "get": {
                "tags": [
                    "Assistant"
                ],
                "summary": "Get an assistant conversation",
                "description": "One conversation as turns (questions; the assistant's text and tool steps) and the actions that wait for the user's confirmation (`pending`). Only the user who started it may read it.",
                "operationId": "getAssistantConversation",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "conversation",
                                                "turns",
                                                "pending"
                                            ],
                                            "properties": {
                                                "conversation": {
                                                    "$ref": "#/components/schemas/AssistantConversationSummary"
                                                },
                                                "turns": {
                                                    "description": "A user turn has `text`; an assistant turn has `text` (its texts joined) and `tools` (the tool calls as small steps).",
                                                    "type": "array",
                                                    "items": {
                                                        "required": [
                                                            "role",
                                                            "id",
                                                            "text",
                                                            "created_at"
                                                        ],
                                                        "properties": {
                                                            "role": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "user",
                                                                    "assistant"
                                                                ]
                                                            },
                                                            "id": {
                                                                "type": "string",
                                                                "format": "uuid"
                                                            },
                                                            "text": {
                                                                "type": "string"
                                                            },
                                                            "tools": {
                                                                "description": "Assistant turns only.",
                                                                "type": "array",
                                                                "items": {
                                                                    "required": [
                                                                        "id",
                                                                        "name",
                                                                        "title",
                                                                        "status"
                                                                    ],
                                                                    "properties": {
                                                                        "id": {
                                                                            "type": "string"
                                                                        },
                                                                        "name": {
                                                                            "type": "string"
                                                                        },
                                                                        "title": {
                                                                            "type": "string"
                                                                        },
                                                                        "status": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "pending",
                                                                                "done",
                                                                                "declined",
                                                                                "error"
                                                                            ]
                                                                        }
                                                                    },
                                                                    "type": "object"
                                                                }
                                                            },
                                                            "created_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                },
                                                "pending": {
                                                    "description": "Actions waiting for the user's confirmation, each as its confirmation card.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "additionalProperties": true
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/AssistantMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "conversation",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/company/{company}/billing": {
            "get": {
                "tags": [
                    "Billing"
                ],
                "summary": "Get billing",
                "description": "Plan, status, trial and renewal dates, entitlements and usage of the location.",
                "operationId": "getBilling",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Billing"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/billing/quote": {
            "get": {
                "tags": [
                    "Billing"
                ],
                "summary": "Price quote",
                "description": "What the business pays on `plan` for `locations` locations (default: its own count, HQ included), in volume bands: same body as the v1 quote.",
                "operationId": "getBillingQuote",
                "parameters": [
                    {
                        "name": "plan",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "starter",
                                "pro",
                                "premium"
                            ]
                        }
                    },
                    {
                        "name": "locations",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100000,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/BillingQuote"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/billing/invoices": {
            "get": {
                "tags": [
                    "Billing"
                ],
                "summary": "List invoices",
                "description": "The location's invoices from Stripe, newest first, read only (drafts left out; cached about two minutes). Owners only (`billing.manage`). Each row: `id`, `number`, `date`, `total`, `amount_due`, `amount_paid` (major unit, e.g. dollars), `currency`, `status` (open, paid, void, uncollectible), `url` = `hosted_invoice_url`, `pdf_url`. Paged with `limit` (12, max 50) and `starting_after` = `meta.next_cursor`. An empty list with `meta.reason` when Stripe does not bill the location itself: `billed_via_agency`, `billed_via_hq`, `no_customer`, `unconfigured`.",
                "operationId": "listBillingInvoices",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 12,
                            "maximum": 50,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "starting_after",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 255
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "id": {
                                                        "type": "string"
                                                    },
                                                    "number": {
                                                        "type": "string",
                                                        "nullable": true
                                                    },
                                                    "date": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "total": {
                                                        "type": "number"
                                                    },
                                                    "amount_due": {
                                                        "type": "number"
                                                    },
                                                    "amount_paid": {
                                                        "type": "number"
                                                    },
                                                    "currency": {
                                                        "type": "string"
                                                    },
                                                    "status": {
                                                        "type": "string"
                                                    },
                                                    "url": {
                                                        "type": "string",
                                                        "format": "uri",
                                                        "nullable": true
                                                    },
                                                    "hosted_invoice_url": {
                                                        "type": "string",
                                                        "format": "uri",
                                                        "nullable": true
                                                    },
                                                    "pdf_url": {
                                                        "type": "string",
                                                        "format": "uri",
                                                        "nullable": true
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "reason": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "enum": [
                                                        "billed_via_agency",
                                                        "billed_via_hq",
                                                        "no_customer",
                                                        "unconfigured"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "Not an owner of the location"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/billing/checkout": {
            "post": {
                "tags": [
                    "Billing"
                ],
                "summary": "Start checkout",
                "description": "Starts a Stripe Checkout for a subscription and returns its URL. The rest of a running trial carries over (no charge until it ends). The base price covers the first location, every attached location is billed at the plan's per-location price in volume bands (any number of locations). Success and cancel return to `https://my.grades.com/billing?checkout=success|canceled&company=<uuid>`.",
                "operationId": "createBillingCheckout",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "plan",
                                    "interval"
                                ],
                                "properties": {
                                    "plan": {
                                        "type": "string",
                                        "enum": [
                                            "starter",
                                            "pro",
                                            "premium"
                                        ]
                                    },
                                    "interval": {
                                        "type": "string",
                                        "enum": [
                                            "monthly",
                                            "yearly"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Checkout URL",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "Not an admin of the location"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/billing/portal": {
            "post": {
                "tags": [
                    "Billing"
                ],
                "summary": "Open customer portal",
                "description": "Returns a Stripe Customer Portal URL (change plan or card, invoices, cancel).",
                "operationId": "createBillingPortal",
                "responses": {
                    "200": {
                        "description": "Portal URL",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "Not an admin of the location"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/billing/apply-coupon": {
            "post": {
                "tags": [
                    "Billing"
                ],
                "summary": "Apply promotion code",
                "description": "Applies a Stripe promotion code: it goes to the subscription when there is one, else it is kept for the next checkout. `meta.result` says which happened. Limited to 5 requests a minute per user (429). (The Client Hub offer is not a code: the Client Hub starts it.)",
                "operationId": "applyBillingCoupon",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "code"
                                ],
                                "properties": {
                                    "code": {
                                        "type": "string",
                                        "example": "<promo-code>",
                                        "maxLength": 64
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Applied; the updated billing state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Billing"
                                        },
                                        "meta": {
                                            "properties": {
                                                "result": {
                                                    "type": "string",
                                                    "enum": [
                                                        "applied",
                                                        "saved_for_checkout"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "Not an admin of the location"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "429": {
                        "description": "Too many attempts"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/billing/hq": {
            "put": {
                "tags": [
                    "Billing"
                ],
                "summary": "Attach to HQ",
                "description": "Bills the location under an HQ's subscription as an extra location (`hq_company`: the HQ uuid; any number of locations, priced in volume bands), or detaches it (`null`). Needs the admin role in both. The HQ's location count is updated in Stripe. Works before Stripe is configured.",
                "operationId": "updateBillingHq",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "hq_company": {
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The updated billing state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Billing"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "Not an admin of the location or the HQ"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/browser-sessions": {
            "get": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "List connected review-site accounts",
                "description": "Dashboard session version of `GET /v1/companies/{company}/browser-sessions`.",
                "operationId": "listBrowserSessions",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1BrowserSession"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1BrowserSessionListMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Connect a review-site account",
                "description": "Dashboard session version of `POST /v1/companies/{company}/browser-sessions`.",
                "operationId": "connectBrowserSession",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1BrowserConnectRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserSession"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1BrowserConnectStartMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/browser-sessions/{session}": {
            "delete": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Disconnect a review-site account",
                "description": "Dashboard session version of `DELETE /v1/companies/{company}/browser-sessions/{session}`.",
                "operationId": "revokeBrowserSession",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/company/{company}/browser-sessions/{session}/connect/{attempt}": {
            "get": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Get a connect attempt",
                "description": "Dashboard session version of `GET /v1/companies/{company}/browser-sessions/{session}/connect/{attempt}`.",
                "operationId": "getBrowserConnectAttempt",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserConnectAttempt"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Cancel a connect attempt",
                "description": "Dashboard session version of `DELETE /v1/companies/{company}/browser-sessions/{session}/connect/{attempt}`.",
                "operationId": "cancelBrowserConnectAttempt",
                "responses": {
                    "204": {
                        "description": "Canceled"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                },
                {
                    "name": "attempt",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/company/{company}/browser-jobs/{job}/evidence": {
            "get": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Get a browser job's evidence",
                "description": "Dashboard session version of `GET /v1/companies/{company}/browser-jobs/{job}/evidence`.",
                "operationId": "getBrowserJobEvidence",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserJobEvidence"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "job",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/companies": {
            "get": {
                "tags": [
                    "Company"
                ],
                "summary": "Get companies",
                "description": "Companies the user is an accepted member of. With `all=1` (platform super admins only, 403 problem+json otherwise) every company in the API v1 shape, as `GET /v1/companies?all=1`: `{data: [V1Company], meta: {count, total, limit, next_cursor, has_more}}` with `q`, `hq`, `limit`, `cursor`.",
                "operationId": "getCompanies",
                "parameters": [
                    {
                        "name": "all",
                        "in": "query",
                        "description": "Super admins only: every company.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "hq",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Companies"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Company"
                ],
                "summary": "Create a company (super admins)",
                "description": "Platform super admins only (403 problem+json otherwise; others use `POST /company`). Dashboard session version of `POST /v1/companies`: the same body, defaults and `201` with the company in the API v1 shape; the super admin is not added as a member.",
                "operationId": "createCompanyRecord",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1CompanyInput"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Company"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/company/{company}": {
            "get": {
                "tags": [
                    "Company"
                ],
                "summary": "Get company",
                "description": "<\\<Description>>",
                "operationId": "getCompany",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SharedIncludeReviewsSources"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/CompanyEx"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Company"
                ],
                "summary": "Update company",
                "description": "<\\<Description>>",
                "operationId": "updateCompany",
                "requestBody": {
                    "$ref": "#/components/requestBodies/CompanyRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Company"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Company"
                ],
                "summary": "Update company fields",
                "description": "Dashboard session version of `PATCH /v1/companies/{company}`: any of the company fields (`name`, `website`, `phone`, `email`, `address` incl. `zip` (merged), `timezone`, `hq_company`, `location_nickname`); `null` clears one. Admins and super admins of the company only (403); answers the company in the API v1 shape.",
                "operationId": "patchCompany",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1CompanyInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Company"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/logo": {
            "get": {
                "tags": [
                    "Company"
                ],
                "summary": "Get company logo",
                "description": "<\\<Description>>",
                "operationId": "getCompanyLogo",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/File"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyLogoNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Company"
                ],
                "summary": "Update company logo",
                "description": "<\\<Description>>",
                "operationId": "updateCompanyLogo",
                "requestBody": {
                    "$ref": "#/components/requestBodies/CompanyLogoRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Company"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/RequestTooLargeError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Company"
                ],
                "summary": "Delete company logo",
                "description": "Removes the uploaded logo: the business then has no current logo and shows the default image (`hasLogo` false). The file is kept in the logo history, never deleted (keep-history rule). Answers the company, as `PUT /company/{company}/logo` does. Removing when there is no logo changes nothing.",
                "operationId": "deleteCompanyLogo",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Company"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/select": {
            "post": {
                "tags": [
                    "Company"
                ],
                "summary": "Select company",
                "description": "<\\<Description>>",
                "operationId": "selectCompany",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SharedIncludeReviewsSources"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/CompanyEx"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/CompanyInvitationNotAccepted"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/ai-settings": {
            "patch": {
                "tags": [
                    "Company"
                ],
                "summary": "Update company AI settings",
                "description": "Update only the company AI Settings. Validates AI fields only — does not require a complete company profile (phone, email, etc.).",
                "operationId": "updateCompanyAiSettings",
                "requestBody": {
                    "$ref": "#/components/requestBodies/AiSettingsRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Company"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/users": {
            "get": {
                "tags": [
                    "Company Users"
                ],
                "summary": "Get company users list",
                "description": "<\\<Description>>",
                "operationId": "getCompanyUsers",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/CompanyUsersList"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/users/invite": {
            "post": {
                "tags": [
                    "Company Users"
                ],
                "summary": "Invite company user",
                "description": "<\\<Description>>",
                "operationId": "inviteCompanyUser",
                "requestBody": {
                    "$ref": "#/components/requestBodies/InviteUserRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/CompanyUser"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/InsufficientPermissions"
                    },
                    "409": {
                        "$ref": "#/components/responses/UserAlreadyExistsInCompany"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/user/{user}": {
            "put": {
                "tags": [
                    "Company Users"
                ],
                "summary": "Update company user",
                "description": "<\\<Description>>",
                "operationId": "updateCompanyUser",
                "requestBody": {
                    "$ref": "#/components/requestBodies/UpdateUserRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/CompanyUser"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/InsufficientPermissions"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyUserNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Company Users"
                ],
                "summary": "Remove company user",
                "description": "<\\<Description>>",
                "operationId": "deleteCompanyUser",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/InsufficientPermissions"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyUserNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/CompanyUserPath"
                }
            ]
        },
        "/company/{company}/user/{user}/resend-invitation": {
            "post": {
                "tags": [
                    "Company Users"
                ],
                "summary": "Resend user invitation",
                "description": "<\\<Description>>",
                "operationId": "resendUserInvitation",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "$ref": "#/components/responses/InsufficientPermissions"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyUserNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/CompanyUserPath"
                }
            ]
        },
        "/company/{company}/sources/discover": {
            "post": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Discover review sources",
                "description": "Dashboard session version of `POST /v1/companies/{company}/sources/discover` (optional `name`, `website`, `city`, `state`, `drivers`); can take up to about two minutes.",
                "operationId": "discoverSources",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "description": "Defaults to the company name.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 250
                                    },
                                    "website": {
                                        "description": "Defaults to the company website.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 255
                                    },
                                    "city": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 255
                                    },
                                    "state": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 255
                                    },
                                    "drivers": {
                                        "description": "Only these sites (default: all known).",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 32
                                        },
                                        "nullable": true,
                                        "maxItems": 40
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SourceCandidate"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/sources/candidates": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "summary": "List source candidates",
                "description": "Dashboard session version of `GET /v1/companies/{company}/sources/candidates` (`status`, `driver`, `limit`, `cursor`).",
                "operationId": "listSourceCandidates",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SourceCandidate"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/sources/candidates/{candidate}/accept": {
            "post": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Accept a source candidate (connect it)",
                "description": "Dashboard session version of `POST /v1/companies/{company}/sources/candidates/{candidate}/accept` (optional `{\"url\": \"...\"}`).",
                "operationId": "acceptSourceCandidate",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "url": {
                                        "description": "Overrides the candidate's URL.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 2048
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "candidate": {
                                                    "$ref": "#/components/schemas/V1SourceCandidate"
                                                },
                                                "source": {
                                                    "$ref": "#/components/schemas/V1Source"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "candidate",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/company/{company}/sources/candidates/{candidate}/reject": {
            "post": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Reject a source candidate",
                "description": "Dashboard session version of `POST /v1/companies/{company}/sources/candidates/{candidate}/reject`.",
                "operationId": "rejectSourceCandidate",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SourceCandidate"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "candidate",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/company/{company}/feeds": {
            "get": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Review feed addresses",
                "description": "Dashboard session version of `GET /v1/companies/{company}/feeds`.",
                "operationId": "feeds",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1FeedUrls"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1FeedsMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/insights": {
            "get": {
                "tags": [
                    "Insights"
                ],
                "summary": "Review Insights",
                "description": "Dashboard session version of `GET /v1/companies/{company}/insights`.",
                "operationId": "reviewInsights",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewInsights"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReviewInsightsMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/badges": {
            "get": {
                "tags": [
                    "Menu"
                ],
                "summary": "Menu badges",
                "description": "The menu counters of the selected location: pending agent actions (and whether there are more than one page of 100), escalated ones, new radar mentions and open recovery cases. Counts only; a part the user may not see, or that failed, is null.",
                "operationId": "getMenuBadges",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "agent_pending": {
                                                    "type": "integer",
                                                    "nullable": true
                                                },
                                                "agent_pending_has_more": {
                                                    "type": "boolean"
                                                },
                                                "agent_escalated": {
                                                    "type": "integer",
                                                    "nullable": true
                                                },
                                                "radar_new": {
                                                    "type": "integer",
                                                    "nullable": true
                                                },
                                                "recovery_open": {
                                                    "type": "integer",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/user/notification-settings": {
            "get": {
                "tags": [
                    "Notification"
                ],
                "summary": "Get notification settings",
                "description": "<\\<Description>>",
                "operationId": "getNotificationSettings",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/NotificationSettings"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Notification"
                ],
                "summary": "Update notification settings",
                "description": "<\\<Description>>",
                "operationId": "updateNotificationSettings",
                "requestBody": {
                    "$ref": "#/components/requestBodies/NotificationSettingsRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/NotificationSettings"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/user/notifications": {
            "get": {
                "tags": [
                    "Notification"
                ],
                "summary": "Get user notifications",
                "description": "<\\<Description>>",
                "operationId": "getNotifications",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/ItemsPerPage"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Notifications"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/user/notification/{notification}": {
            "put": {
                "tags": [
                    "Notification"
                ],
                "summary": "Update user notification",
                "description": "<\\<Description>>",
                "operationId": "updateNotification",
                "requestBody": {
                    "$ref": "#/components/requestBodies/NotificationRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Notification"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotificationNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/NotificationPath"
                }
            ]
        },
        "/user/notifications/all": {
            "put": {
                "tags": [
                    "Notification"
                ],
                "summary": "Update all user notifications",
                "description": "<\\<Description>>",
                "operationId": "updateAllNotifications",
                "requestBody": {
                    "$ref": "#/components/requestBodies/NotificationRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/user/oauth-connections": {
            "get": {
                "tags": [
                    "ApiKey"
                ],
                "summary": "List connected apps",
                "description": "Lists the apps connected to the signed-in user's account by signing in with Grades.com (AI apps and automation platforms): name, kind (`zapier`, `make`, `n8n`, `ai`), the host a self-registered app returns to, what it may do (plain-English sentences), the businesses it may see (null = all, also ones added later), when it was connected and last refreshed, and how many webhooks it created. Never a token.",
                "operationId": "listOAuthConnections",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "id": {
                                                        "type": "string",
                                                        "format": "uuid"
                                                    },
                                                    "app": {
                                                        "properties": {
                                                            "name": {
                                                                "type": "string",
                                                                "nullable": true
                                                            },
                                                            "kind": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "zapier",
                                                                    "make",
                                                                    "n8n",
                                                                    "android",
                                                                    "ai"
                                                                ]
                                                            },
                                                            "host": {
                                                                "type": "string",
                                                                "nullable": true
                                                            }
                                                        },
                                                        "type": "object"
                                                    },
                                                    "scopes": {
                                                        "type": "array",
                                                        "items": {
                                                            "properties": {
                                                                "scope": {
                                                                    "type": "string"
                                                                },
                                                                "sentence": {
                                                                    "type": "string"
                                                                }
                                                            },
                                                            "type": "object"
                                                        }
                                                    },
                                                    "businesses": {
                                                        "type": "array",
                                                        "items": {
                                                            "properties": {
                                                                "uuid": {
                                                                    "type": "string",
                                                                    "format": "uuid"
                                                                },
                                                                "name": {
                                                                    "type": "string"
                                                                }
                                                            },
                                                            "type": "object"
                                                        },
                                                        "nullable": true
                                                    },
                                                    "connected_at": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "last_used_at": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "expires_at": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    },
                                                    "webhooks": {
                                                        "type": "integer"
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/user/oauth-connections/{connection}": {
            "delete": {
                "tags": [
                    "ApiKey"
                ],
                "summary": "Disconnect app",
                "description": "Disconnects an app: its tokens stop working at once and the webhooks it created stop.",
                "operationId": "revokeOAuthConnection",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/ResourceNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "name": "connection",
                    "in": "path",
                    "description": "Connection id (the grant id from the list).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/admin/browser-accounts": {
            "get": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "List the Grades-owned reporter accounts",
                "description": "Dashboard session version of `GET /v1/admin/browser-accounts`.",
                "operationId": "listPlatformBrowserAccounts",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1PlatformBrowserAccount"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1PlatformBrowserAccountListMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Connect a Grades-owned reporter account",
                "description": "Dashboard session version of `POST /v1/admin/browser-accounts`.",
                "operationId": "connectPlatformBrowserAccount",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1BrowserConnectRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserSession"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1BrowserConnectStartMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/admin/browser-accounts/{session}": {
            "delete": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Disconnect a Grades-owned reporter account",
                "description": "Dashboard session version of `DELETE /v1/admin/browser-accounts/{session}`.",
                "operationId": "revokePlatformBrowserAccount",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/admin/browser-accounts/{session}/connect/{attempt}": {
            "get": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Get a reporter account connect attempt",
                "description": "Dashboard session version of `GET /v1/admin/browser-accounts/{session}/connect/{attempt}`.",
                "operationId": "getPlatformBrowserConnectAttempt",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserConnectAttempt"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "BrowserSessions"
                ],
                "summary": "Cancel a reporter account connect attempt",
                "description": "Dashboard session version of `DELETE /v1/admin/browser-accounts/{session}/connect/{attempt}`.",
                "operationId": "cancelPlatformBrowserConnectAttempt",
                "responses": {
                    "204": {
                        "description": "Canceled"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                },
                {
                    "name": "attempt",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/user/companies/{company}/publishable-keys": {
            "get": {
                "tags": [
                    "PublishableKey"
                ],
                "summary": "List publishable keys",
                "description": "Lists the company's publishable keys, revoked ones included (never the key itself).",
                "operationId": "listPublishableKeys",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/PublishableKey"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    },
                    {
                        "dashboardSession": []
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "PublishableKey"
                ],
                "summary": "Create publishable key",
                "description": "Creates a publishable key (`gk_pub_...`) for the public reviews API. The key is returned once. `allowed_origins` limits which websites may call the API from a browser.",
                "operationId": "createPublishableKey",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "Main website",
                                        "maxLength": 100
                                    },
                                    "allowed_origins": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "example": "https://www.example.com"
                                        },
                                        "nullable": true,
                                        "maxItems": 20
                                    },
                                    "integration": {
                                        "description": "Which integration the key is for (a label for the key list; it grants nothing).",
                                        "type": "string",
                                        "example": "wordpress",
                                        "nullable": true,
                                        "enum": [
                                            "wordpress"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/CreatedPublishableKey"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    },
                    {
                        "dashboardSession": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/user/companies/{company}/publishable-keys/{publishableKey}": {
            "delete": {
                "tags": [
                    "PublishableKey"
                ],
                "summary": "Revoke publishable key",
                "description": "Revokes a publishable key. Websites using it stop getting reviews (cached responses may live up to the cache max-age).",
                "operationId": "revokePublishableKey",
                "responses": {
                    "204": {
                        "description": "Revoked"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/ResourceNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    },
                    {
                        "dashboardSession": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "publishableKey",
                    "in": "path",
                    "description": "Publishable key id.",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/company/{company}/radar/settings": {
            "get": {
                "tags": [
                    "Radar"
                ],
                "summary": "Review radar settings",
                "description": "Dashboard session version of `GET /v1/companies/{company}/radar/settings`.",
                "operationId": "getRadarSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RadarSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Radar"
                ],
                "summary": "Update review radar settings",
                "description": "Dashboard session version of `PUT /v1/companies/{company}/radar/settings` (`{\"enabled\": true}`).",
                "operationId": "updateRadarSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "enabled"
                                ],
                                "properties": {
                                    "enabled": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RadarSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/radar/scan": {
            "post": {
                "tags": [
                    "Radar"
                ],
                "summary": "Scan the web for mentions now",
                "description": "Dashboard session version of `POST /v1/companies/{company}/radar/scan`: up to about two minutes; 429 (with `Retry-After`) within 6 hours of the last scan, 503 `radar_unavailable` without an Apify token, 502 `radar_scan_failed` when the search failed.",
                "operationId": "runRadarScan",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "scan": {
                                                    "$ref": "#/components/schemas/V1RadarScan"
                                                },
                                                "new_mentions": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/V1ReviewMention"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/radar/mentions": {
            "get": {
                "tags": [
                    "Radar"
                ],
                "summary": "List web mentions",
                "description": "Dashboard session version of `GET /v1/companies/{company}/radar/mentions` (same filters: `status`, `since`, `engine`, `tracked`, `review_pages`, `limit`, `cursor`; same `meta`).",
                "operationId": "listRadarMentions",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewMention"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/radar/mentions/{mention}": {
            "patch": {
                "tags": [
                    "Radar"
                ],
                "summary": "Mark a mention seen, dismissed or new",
                "description": "Dashboard session version of `PATCH /v1/companies/{company}/radar/mentions/{mention}` (`{\"status\": \"new\" | \"seen\" | \"dismissed\"}`).",
                "operationId": "updateRadarMention",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "status"
                                ],
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "new",
                                            "seen",
                                            "dismissed"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewMention"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "mention",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/company/{company}/radar/ai-probe": {
            "post": {
                "tags": [
                    "Radar"
                ],
                "summary": "Ask the AI assistants now",
                "description": "Dashboard session version of `POST /v1/companies/{company}/radar/ai-probe` (optional `{\"engines\": [...]}`): up to about 90 seconds; 429 within 24 hours of the last probe, 503 `ai_probe_unavailable` when no engine has a key, 502 `ai_probe_failed` when none answered.",
                "operationId": "runAiProbe",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "engines": {
                                        "description": "Only these engines (default: every configured engine).",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "gemini",
                                                "openai",
                                                "perplexity",
                                                "anthropic"
                                            ]
                                        },
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AiProbeRunResult"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1AiProbeRunMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/radar/ai-perception": {
            "get": {
                "tags": [
                    "Radar"
                ],
                "summary": "AI Reputation",
                "description": "Dashboard session version of `GET /v1/companies/{company}/radar/ai-perception` (filters `engine`, `since`).",
                "operationId": "getAiPerception",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AiPerception"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1AiPerceptionMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/review": {
            "post": {
                "tags": [
                    "Review"
                ],
                "summary": "Add review (retired)",
                "description": "Retired: answers 410. Use POST /v1/companies/{uuid}/reviews.",
                "operationId": "addReview",
                "responses": {
                    "410": {
                        "description": "Gone: use POST /v1/companies/{uuid}/reviews.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "message",
                                        "replacement"
                                    ],
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "deprecated": true
                                        },
                                        "replacement": {
                                            "type": "string",
                                            "example": "/api/v1/companies/{uuid}/reviews",
                                            "deprecated": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "deprecated": true,
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/reviews": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Get reviews",
                "description": "<\\<Description>>",
                "operationId": "getReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/ItemsPerPage"
                    },
                    {
                        "$ref": "#/components/parameters/StartDate"
                    },
                    {
                        "$ref": "#/components/parameters/EndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewType"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewSourceDrivers"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMinRating"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMaxRating"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewHasCompanyResponse"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMinLength"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMaxLength"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewIsRecommended"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewHideInWidget"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewS"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewsOrderBy"
                    },
                    {
                        "$ref": "#/components/parameters/IncludeTotalQuantity"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewRemoved"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewEdited"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Reviews"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/reviews/export": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Export reviews",
                "description": "<\\<Description>>",
                "operationId": "downloadReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReviewSourceDrivers"
                    },
                    {
                        "$ref": "#/components/parameters/StartDate"
                    },
                    {
                        "$ref": "#/components/parameters/EndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewsExportFileType"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/File"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/review/{review}": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Get review",
                "description": "<\\<Description>>",
                "operationId": "getReview",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReviewIncludeSource"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewEx"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/ReviewNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Review"
                ],
                "summary": "Update review",
                "description": "<\\<Description>>",
                "operationId": "updateReview",
                "requestBody": {
                    "$ref": "#/components/requestBodies/ReviewRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Review"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Review"
                ],
                "summary": "Delete review",
                "description": "<\\<Description>>",
                "operationId": "deleteReview",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/ReviewNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/company/{company}/review/{review}/history": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Review history (archive)",
                "description": "Dashboard session version of `GET /v1/companies/{company}/reviews/{review}/history`: the review archive (earlier versions, removal).",
                "operationId": "getReviewHistory",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewHistory"
                                        },
                                        "meta": {
                                            "properties": {
                                                "yelp_text": {
                                                    "$ref": "#/components/schemas/V1YelpTextMeta"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/ReviewNotFound"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/company/{company}/review-pages": {
            "get": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "List review pages",
                "description": "Dashboard session version of `GET /v1/companies/{company}/review-pages`.",
                "operationId": "listReviewPages",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewPage"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Create a review page",
                "description": "Dashboard session version of `POST /v1/companies/{company}/review-pages`.",
                "operationId": "createReviewPage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "type": "object",
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ReviewPageSettings"
                                    },
                                    {
                                        "properties": {
                                            "make_default": {
                                                "type": "boolean"
                                            },
                                            "copy_from": {
                                                "description": "Page id or slug to duplicate.",
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 64
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/review-pages/{page}": {
            "get": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Get a review page",
                "description": "Dashboard session version of `GET /v1/companies/{company}/review-pages/{page}`.",
                "operationId": "getReviewPage",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Update a review page",
                "description": "Dashboard session version of `PUT /v1/companies/{company}/review-pages/{page}` (PATCH works the same).",
                "operationId": "updateReviewPage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewPageSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Delete a review page",
                "description": "Dashboard session version of `DELETE /v1/companies/{company}/review-pages/{page}`.",
                "operationId": "deleteReviewPage",
                "responses": {
                    "204": {
                        "description": "Deleted"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/default": {
            "post": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Make a review page the default",
                "description": "Dashboard session version of `POST /v1/companies/{company}/review-pages/{page}/default`.",
                "operationId": "makeDefaultReviewPage",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/links": {
            "post": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Add a review page link",
                "description": "Dashboard session version of `POST /v1/companies/{company}/review-pages/{page}/links`.",
                "operationId": "addReviewPageLink",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ReviewPageLinkInput"
                                    },
                                    {
                                        "properties": {
                                            "position": {
                                                "type": "integer",
                                                "nullable": true,
                                                "minimum": 0
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "required": [
                                                "link_id"
                                            ],
                                            "properties": {
                                                "link_id": {
                                                    "description": "Id of the new link.",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/links/reorder": {
            "patch": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Reorder review page links",
                "description": "Dashboard session version of `PATCH /v1/companies/{company}/review-pages/{page}/links/reorder`.",
                "operationId": "reorderReviewPageLinks",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "ids"
                                ],
                                "properties": {
                                    "ids": {
                                        "description": "Every link id of the page exactly once, in the new order.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 64
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/links/{link}": {
            "delete": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Remove a review page link",
                "description": "Dashboard session version of `DELETE /v1/companies/{company}/review-pages/{page}/links/{link}`.",
                "operationId": "removeReviewPageLink",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "link",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/suggestions": {
            "get": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Suggested order of a review page",
                "description": "Dashboard session version of `GET /v1/companies/{company}/review-pages/{page}/suggestions`.",
                "operationId": "getReviewPageSuggestions",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPageSuggestions"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/preview": {
            "post": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Preview a review page",
                "description": "Dashboard session version of `POST /v1/companies/{company}/review-pages/{page}/preview`.",
                "operationId": "previewReviewPage",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewPageSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPagePreview"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/activity": {
            "get": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Get review page activity",
                "description": "Dashboard session version of `GET /v1/companies/{company}/review-pages/{page}/activity`.",
                "operationId": "getReviewPageActivity",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPageActivity"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/review-pages/{page}/feedback": {
            "get": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "List review page feedback",
                "description": "Dashboard session version of `GET /v1/companies/{company}/review-pages/{page}/feedback`.",
                "operationId": "listReviewPageFeedback",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewPageFeedback"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/agent/reviews/{review}/policy-check": {
            "get": {
                "tags": [
                    "Agent"
                ],
                "summary": "Policy check state of a review",
                "description": "Where one review stands in Review Disputes: `status` (not_checked, report, reported, honest, dismissed, expired), `checkable` and, when it cannot be checked now, `reason` (removed, no_review_site, not_low_rated, plan, role, limit); `action` is the flag action (V1AgentAction) or null; `case` the Review Disputes case or null; `automatic` whether the agent checks new low-rated reviews by itself. No model call.",
                "operationId": "getReviewPolicyCheck",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentPolicyCheck"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Agent"
                ],
                "summary": "Check a review against its site's rules",
                "description": "Checks one low-rated review against its site's rules now (one model call; at most `agent.reports.on_demand_per_day` a day per business), whether or not the agent or Review Disputes is on. Needs the \"Drafts of reports to review sites\" plan feature (402) and a role that approves agent actions (403 `role_forbidden`). A review that already has a decision is returned as it is. A report it finds is `pending` and waits for a person; nothing is filed. 409 `review_removed`, `no_review_site`, `not_low_rated`; 429 `daily_limit`, `check_running`; 503 `check_failed`.",
                "operationId": "runReviewPolicyCheck",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentPolicyCheck"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/company/{company}/review/{review}/reply": {
            "get": {
                "tags": [
                    "ReviewReply"
                ],
                "summary": "Get review reply",
                "description": "Get current review reply and last sync attempt",
                "operationId": "getReviewReply",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewReplyShow"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "ReviewReply"
                ],
                "summary": "Upsert review reply",
                "description": "Create or update review reply",
                "operationId": "addReviewReply",
                "requestBody": {
                    "$ref": "#/components/requestBodies/ReviewReplyRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewReplyUpsert"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "ReviewReply"
                ],
                "summary": "Delete review reply",
                "description": "Delete review reply and create sync attempt for source",
                "operationId": "deleteReviewReply",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewReplyDelete"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewReplyPath"
                }
            ]
        },
        "/company/{company}/reviews-sources": {
            "get": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Get reviews sources",
                "description": "<\\<Description>>",
                "operationId": "getReviewsSources",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSources"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/reviews-source/{source}": {
            "get": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Get reviews source",
                "description": "<\\<Description>>",
                "operationId": "getReviewsSource",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Enable or disable a reviews source",
                "description": "Enables or disables a connected source (admins and super admins). A disabled source is kept with its reviews but no longer fetched. Settings are changed through `PUT /company/{company}/reviews-source/{source}/config`; `params` and `config` are refused here.",
                "operationId": "updateReviewsSource",
                "requestBody": {
                    "$ref": "#/components/requestBodies/ReviewsSourceActiveRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "Not an admin of the company"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Add reviews source",
                "description": "<\\<Description>>",
                "operationId": "addReviewsSource",
                "requestBody": {
                    "$ref": "#/components/requestBodies/ReviewsSourceRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Delete reviews source",
                "description": "<\\<Description>>",
                "operationId": "deleteReviewsSource",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewsSourcePath"
                }
            ]
        },
        "/company/{company}/reviews-source/auth": {
            "post": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Authenticate review source",
                "description": "<\\<Description>>",
                "operationId": "authReviewSource",
                "requestBody": {
                    "$ref": "#/components/requestBodies/AuthReviewSourceRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/AuthReviewSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/frontend_redirect_url"
                }
            ]
        },
        "/company/{company}/reviews-source/{source}/config": {
            "put": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Update reviews source config",
                "description": "Changes the settings of a connected source (admins and super admins). Writable keys per driver: google `account_id` + `location_id`, facebook `page_id`, g2 `product_id`, URL drivers (yelp, bbb, thumbtack and the Apify-backed drivers) `page_url` (or `link`), which must be on the driver's hosts as when connecting. Any other key is a 400.",
                "operationId": "updateConfig",
                "requestBody": {
                    "$ref": "#/components/requestBodies/ReviewsSourceConfigRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "Not an admin of the company"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewsSourcePath"
                }
            ]
        },
        "/company/{company}/reviews-source/facebook/pages": {
            "get": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Get facebook pages",
                "description": "<\\<Description>>",
                "operationId": "getReviewsSourcePages",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/reviews-source/google/accounts": {
            "get": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Get google reviews source accounts",
                "description": "<\\<Description>>",
                "operationId": "getReviewsSourceAccounts",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "pageToken",
                    "in": "query",
                    "description": "Token for pagination",
                    "required": false,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/reviews-source/google/accounts/{account_id}/locations": {
            "get": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Get google reviews source locations",
                "description": "<\\<Description>>",
                "operationId": "getReviewsSourceAccountLocations",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsSource"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "account_id",
                    "in": "path",
                    "description": "Google Account ID",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "pageToken",
                    "in": "query",
                    "description": "Token for pagination",
                    "required": false,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/company/{company}/reviews-stats": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Get reviews statistics",
                "description": "<\\<Description>>",
                "operationId": "getReviewsStats",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsStats"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/reviews-stats/by-site": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Get review statistics per site",
                "description": "Rated reviews that count (still on their site) per review platform, largest first: `platform` (`google`, `yelp`, `direct` = added through the API, `grades` = left on Grades.com, ...), `name`, `sources` (the collectors behind it), `total`, `average_rating` (weighted, null without ratings) and `ratings` (count per star 1-5). Client Hub Google reviews are `google`, not `api`.",
                "operationId": "getReviewsStatsBySite",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "platform": {
                                                        "type": "string",
                                                        "example": "google"
                                                    },
                                                    "name": {
                                                        "type": "string",
                                                        "example": "Google"
                                                    },
                                                    "sources": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        },
                                                        "example": [
                                                            "api",
                                                            "google_maps"
                                                        ]
                                                    },
                                                    "total": {
                                                        "type": "integer",
                                                        "example": 12
                                                    },
                                                    "average_rating": {
                                                        "type": "number",
                                                        "format": "float",
                                                        "example": 4.75,
                                                        "nullable": true
                                                    },
                                                    "ratings": {
                                                        "description": "Count per star, keys 1-5.",
                                                        "type": "object",
                                                        "example": {
                                                            "1": 0,
                                                            "2": 0,
                                                            "3": 1,
                                                            "4": 1,
                                                            "5": 10
                                                        }
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/reviews-stats-by-days/current-month": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Get reviews statistics for current month",
                "description": "<\\<Description>>",
                "operationId": "getReviewsStatsByDays",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsStatsByDays"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/reviews-stats-by-days/year/{year}/month/{month}": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Get reviews statistics for month of the year",
                "description": "<\\<Description>>",
                "operationId": "getReviewsStatsByDaysForMonth",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsStatsByDays"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewStatsYearPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewStatsMonthPath"
                }
            ]
        },
        "/company/{company}/reviews-stats-by-days/year/{year}": {
            "get": {
                "tags": [
                    "Review"
                ],
                "summary": "Get reviews statistics for year",
                "description": "<\\<Description>>",
                "operationId": "getReviewsStatsByDaysForYear",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReviewStatsYearPath"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ReviewsStatsByDays"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewStatsYearPath"
                }
            ]
        },
        "/company/{company}/showcase": {
            "get": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Review Showcase selection",
                "description": "Dashboard session version of `GET /v1/companies/{company}/showcase`.",
                "operationId": "showcase",
                "responses": {
                    "200": {
                        "description": "OK (`format=json`; the other formats answer the raw document).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ShowcaseReview"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ShowcaseMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/showcases": {
            "get": {
                "tags": [
                    "Showcase"
                ],
                "summary": "List saved showcases",
                "description": "Dashboard session version of `GET /v1/companies/{company}/showcases`.",
                "operationId": "listShowcases",
                "responses": {
                    "200": {
                        "description": "OK: the same `meta` (`count`, `limits`, `script`) as the v1 list.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewShowcase"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "limits": {
                                                    "description": "The plan's Review Showcase limits (as in v1).",
                                                    "type": "object",
                                                    "additionalProperties": true
                                                },
                                                "script": {
                                                    "description": "The embed script URL.",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Save a showcase",
                "description": "Dashboard session version of `POST /v1/companies/{company}/showcases`.",
                "operationId": "createShowcase",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ShowcaseInput"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/showcases/{showcase}": {
            "get": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Get a saved showcase",
                "description": "Dashboard session version of `GET /v1/companies/{company}/showcases/{showcase}`.",
                "operationId": "getShowcase",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "properties": {
                                                "history": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/V1SavedChange"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Update a saved showcase",
                "description": "Dashboard session version of `PUT /v1/companies/{company}/showcases/{showcase}`.",
                "operationId": "updateShowcase",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ShowcaseInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Delete a saved showcase",
                "description": "Dashboard session version of `DELETE /v1/companies/{company}/showcases/{showcase}`.",
                "operationId": "deleteShowcase",
                "responses": {
                    "204": {
                        "description": "Deleted"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Update a saved showcase",
                "description": "Dashboard session version of `PATCH /v1/companies/{company}/showcases/{showcase}`.",
                "operationId": "patchShowcase",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ShowcaseInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "showcase",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/company/{company}/sources/requests": {
            "get": {
                "tags": [
                    "Discovery"
                ],
                "summary": "List site requests",
                "description": "Dashboard session version of `GET /v1/companies/{company}/sources/requests`: the company's tracked site requests with status, due date (two weeks after the request) and our answer.",
                "operationId": "listSiteRequests",
                "responses": {
                    "200": {
                        "description": "The requests",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SiteRequestCase"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "Discovery"
                ],
                "summary": "Request a review site",
                "description": "Dashboard session version of `POST /v1/companies/{company}/sources/requests` (`url`, optional `note`): 201 connected, 200 already connected, 202 recorded in the demand queue.",
                "operationId": "requestReviewSite",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "url"
                                ],
                                "properties": {
                                    "url": {
                                        "description": "The business's page on the review site.",
                                        "type": "string",
                                        "format": "url",
                                        "maxLength": 2048
                                    },
                                    "note": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 1000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Recorded (201 when the site was connected)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SiteRequestResult"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/sources/{source}/reply-api": {
            "get": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Show a source's reply API connection",
                "description": "Dashboard session version of `GET /v1/companies/{company}/sources/{source}/reply-api`.",
                "operationId": "showSourceReplyApi",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SourceReplyApi"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Connect a source's reply API",
                "description": "Dashboard session version of `PUT /v1/companies/{company}/sources/{source}/reply-api`.",
                "operationId": "connectSourceReplyApi",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "api_key",
                                    "api_secret",
                                    "business_user_id"
                                ],
                                "properties": {
                                    "api_key": {
                                        "type": "string",
                                        "pattern": "^[A-Za-z0-9._-]+$",
                                        "maxLength": 200,
                                        "minLength": 8
                                    },
                                    "api_secret": {
                                        "type": "string",
                                        "pattern": "^[A-Za-z0-9._-]+$",
                                        "maxLength": 200,
                                        "minLength": 8
                                    },
                                    "business_user_id": {
                                        "type": "string",
                                        "pattern": "^[A-Za-z0-9-]+$",
                                        "maxLength": 64,
                                        "minLength": 8
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Connected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SourceReplyApi"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Disconnect a source's reply API",
                "description": "Dashboard session version of `DELETE /v1/companies/{company}/sources/{source}/reply-api`.",
                "operationId": "disconnectSourceReplyApi",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "source",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "example": "trustpilot"
                    }
                }
            ]
        },
        "/user": {
            "get": {
                "tags": [
                    "User"
                ],
                "summary": "Get current user",
                "description": "<\\<Description>>",
                "operationId": "getUser",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/User"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "User"
                ],
                "summary": "Update current user",
                "description": "<\\<Description>>",
                "operationId": "updateUser",
                "requestBody": {
                    "$ref": "#/components/requestBodies/UserRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/User"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/user/login": {
            "post": {
                "tags": [
                    "User"
                ],
                "summary": "Login user",
                "description": "<\\<Description>>",
                "operationId": "userLogin",
                "requestBody": {
                    "$ref": "#/components/requestBodies/UserLoginRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/UserLogin"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "404": {
                        "$ref": "#/components/responses/UserNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": []
            }
        },
        "/user/register": {
            "post": {
                "tags": [
                    "User"
                ],
                "summary": "Register user",
                "description": "<\\<Description>>",
                "operationId": "userRegister",
                "requestBody": {
                    "$ref": "#/components/requestBodies/UserRegisterRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/User"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "409": {
                        "$ref": "#/components/responses/UserAlreadyExists"
                    },
                    "422": {
                        "$ref": "#/components/responses/CompanyAlreadyExists"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": []
            }
        },
        "/user/send-reset-password-link": {
            "post": {
                "tags": [
                    "User"
                ],
                "summary": "Send password reset link",
                "description": "<\\<Description>>",
                "operationId": "sendResetPasswordLink",
                "requestBody": {
                    "$ref": "#/components/requestBodies/SendResetPasswordLinkRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/UserNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": []
            }
        },
        "/user/update-password": {
            "post": {
                "tags": [
                    "User"
                ],
                "summary": "Update user password",
                "description": "<\\<Description>>",
                "operationId": "updatePassword",
                "requestBody": {
                    "$ref": "#/components/requestBodies/UpdatePasswordRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "404": {
                        "$ref": "#/components/responses/TokenNotFound"
                    },
                    "410": {
                        "$ref": "#/components/responses/TokenExpired"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": []
            }
        },
        "/v1/agencies/{agency}/client-invitations": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "List an agency's client invitations",
                "description": "Scope: `companies:read`; agency admins. E-mail invitations to business owners (`status`: pending (default), accepted, declined, revoked, expired, all), newest first.",
                "operationId": "v1ListAgencyClientInvitations",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pending",
                                "accepted",
                                "declined",
                                "revoked",
                                "expired",
                                "all"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AgencyClientInvitation"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count",
                                                "status"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "pending",
                                                        "accepted",
                                                        "declined",
                                                        "revoked",
                                                        "expired",
                                                        "all"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Invite a business owner by e-mail",
                "description": "Scope: `companies:write`; agency admins. `{email, business_name?, listing?, plan?, message?}`: e-mails the owner of a business the agency does not manage yet a link to accept or decline (14 days). `listing` is a public directory listing id (from `GET /directory/search`); `business_name` or `listing` is required. Nothing is granted before the owner, signed in with that address, accepts for one of their own businesses. Inviting the same address again renews the pending invitation (new link).",
                "operationId": "v1CreateAgencyClientInvitation",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191
                                    },
                                    "business_name": {
                                        "description": "Required unless `listing` is given.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 191
                                    },
                                    "listing": {
                                        "description": "A public directory listing id; 404 when unknown.",
                                        "type": "integer",
                                        "nullable": true,
                                        "minimum": 1
                                    },
                                    "plan": {
                                        "description": "One of the agency's plans; default its default plan.",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "starter",
                                            "pro",
                                            "premium"
                                        ]
                                    },
                                    "message": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 500
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Invited: the client invitation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyClientInvitation"
                                        },
                                        "meta": {
                                            "required": [
                                                "status"
                                            ],
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "invited"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "name": "agency",
                    "in": "path",
                    "description": "Agency uuid or slug.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/agencies/{agency}/client-invitations/{invitation}": {
            "delete": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Revoke a client invitation",
                "description": "Scope: `companies:write`; agency admins. Revokes a pending invitation (its link stops working; the row is kept as `revoked`). 409 `invitation_closed` once accepted, declined or revoked.",
                "operationId": "v1RevokeAgencyClientInvitation",
                "responses": {
                    "200": {
                        "description": "OK: the revoked invitation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyClientInvitation"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "name": "agency",
                    "in": "path",
                    "description": "Agency uuid or slug.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "invitation",
                    "in": "path",
                    "description": "Invitation uuid.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/agencies/{agency}/client-invitations/{invitation}/resend": {
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Resend a client invitation",
                "description": "Scope: `companies:write`; agency admins. A new link and expiry, e-mailed again (the old link stops working). 409 `invitation_closed` once accepted, declined or revoked.",
                "operationId": "v1ResendAgencyClientInvitation",
                "responses": {
                    "200": {
                        "description": "OK: the invitation with its new expiry.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyClientInvitation"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "name": "agency",
                    "in": "path",
                    "description": "Agency uuid or slug.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "invitation",
                    "in": "path",
                    "description": "Invitation uuid.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/agent/settings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get review agent settings",
                "description": "Scope: `companies:read`. The company's review agent settings (the defaults until saved). `meta.ai_drafts_remaining_this_month` is what is left of the monthly AI drafts the agent shares with the dashboard.",
                "operationId": "v1GetAgentSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentSettings"
                                        },
                                        "meta": {
                                            "properties": {
                                                "ai_drafts_remaining_this_month": {
                                                    "type": "integer"
                                                },
                                                "auto_reply_all_available": {
                                                    "description": "The plan includes reply mode `auto_all` (Premium).",
                                                    "type": "boolean"
                                                },
                                                "timezone": {
                                                    "description": "The timezone of the quiet hours and the daily cap (the company's).",
                                                    "type": "string",
                                                    "example": "America/New_York"
                                                },
                                                "removal_filing_available": {
                                                    "description": "The plan includes removal reports filed without a person (Premium `removal_filing`).",
                                                    "type": "boolean"
                                                },
                                                "removal_filing_live": {
                                                    "description": "grades.com files reports itself now (the browser is on); otherwise auto reports are prepared for you to file.",
                                                    "type": "boolean"
                                                },
                                                "removal_filing_hands_free": {
                                                    "description": "Reports may be filed without a person at all (report rules `approval` other than `all`). False: every report waits for a person to approve it and such rules answer 409 `hands_free_unavailable`.",
                                                    "type": "boolean"
                                                },
                                                "report_consent_version": {
                                                    "type": "string"
                                                },
                                                "report_consent_text": {
                                                    "type": "string"
                                                },
                                                "voices": {
                                                    "description": "Reply voice presets: key, label, style and two example sentences.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object"
                                                    }
                                                },
                                                "report_grounds": {
                                                    "description": "Grounds a removal report may be based on: id and meaning.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update review agent settings",
                "description": "Scope: `reviews:write`. Saves the fields sent (at least one); the others keep their values. `rules` takes the rule set (any subset; `approval.replies` / `approval.reports` map onto the modes), `reset` puts blocks back to their defaults (voice, reply, reports). Hands-free removal reports need `report_consent_version` = `meta.report_consent_version` once (409 `consent_required` with the text otherwise); 423 `setting_locked` for a field locked on this location.",
                "operationId": "v1UpdateAgentSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1AgentSettingsUpdate"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentSettings"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "423": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/actions": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review agent actions",
                "description": "Scope: `reviews:read`. The approval queue and history, newest first. Cursor pagination: pass `meta.next_cursor` back as `cursor`. `meta.total` counts the actions matching the filters (all pages); `meta.pending_count` counts all pending actions of the company.",
                "operationId": "v1ListAgentActions",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pending",
                                "approved",
                                "rejected",
                                "executed",
                                "failed",
                                "expired",
                                "skipped"
                            ]
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "reply",
                                "flag"
                            ]
                        }
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "description": "`report`: removal reports only (flag actions, incl. the `skipped` decisions of the engine, with `report` and `waiting_for`); `reply`: replies only.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "reply",
                                "report"
                            ]
                        }
                    },
                    {
                        "name": "escalated",
                        "in": "query",
                        "description": "`true`: only actions reply mode `auto_all` kept for a person (`escalation` set); `false`: only the others.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "assigned",
                        "in": "query",
                        "description": "`me`: only when the caller gets this company's approval notices (an assigned approver, else the owners and admins, else the HQ's owners; www/docs/roles.md section 7), else an empty list.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "me"
                            ]
                        }
                    },
                    {
                        "name": "review",
                        "in": "query",
                        "description": "Only actions of this review (uuid).",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 25,
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AgentAction"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                },
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "pending_count": {
                                                    "type": "integer"
                                                },
                                                "escalated_count": {
                                                    "description": "Pending actions reply mode `auto_all` kept for a person.",
                                                    "type": "integer"
                                                },
                                                "assigned_to_me": {
                                                    "description": "Whether the caller gets this company's approval notices.",
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/actions/{action}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a review agent action",
                "description": "Scope: `reviews:read`. One agent action.",
                "operationId": "v1GetAgentAction",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/actions/{action}/approve": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Approve a review agent action",
                "description": "Scope: `reviews:write`. Approves a pending (or failed) action and carries it out at once. reply: `text` replaces the draft; posted where the site has a reply API and the reply mode is `approve`/`auto_positive`, otherwise stored in Grades (`result.manual_url`). flag: `text` replaces the report text; creates a review flag (`result.flag_id`, `result.next_steps`); Grades never reports the review itself. Answers the action: `status` is `executed`, or `failed` with `error` (e.g. Google refused the reply). 409 when the action is no longer pending or failed; 422 when a reply has no draft and no `text`, or when a flag is of a review on no review site (left on Grades.com or added by the business): nothing is sent and the flag stays pending until rejected.",
                "operationId": "v1ApproveAgentAction",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "text": {
                                        "description": "Edited reply (max 4000) or report text (max 5000).",
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/actions/{action}/reject": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Reject a review agent action",
                "description": "Scope: `reviews:write`. Rejects a pending (or failed) action; nothing is posted or flagged. `reason` is kept in `result.reason`, `reason_code` in `result.reason_code`; the agent learns from both (docs/review-agent.md \"Constantly improving\"). 409 when the action is no longer pending or failed.",
                "operationId": "v1RejectAgentAction",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 1000
                                    },
                                    "reason_code": {
                                        "description": "Why, as a category the agent learns from.",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "wrong_tone",
                                            "too_long",
                                            "too_short",
                                            "inaccurate",
                                            "too_generic",
                                            "wrong_language",
                                            "should_not_reply",
                                            "other"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/triage": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Run the review agent now",
                "description": "Scope: `reviews:write`. Triages the company's new reviews now instead of waiting for the next scheduled run (every 10 minutes) and answers the counts. 422 when the agent is disabled; 429 (with `Retry-After`) when the company was triaged in the last 5 minutes or a run is in progress.",
                "operationId": "v1RunAgentTriage",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentTriageResult"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/settings/preview-voice": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Preview a reply voice",
                "description": "Scope: `reviews:write`. Drafts one reply for a fixed sample review (`sample`: positive or negative) in the voice sent (`reply_voice`, else the saved one) with the company's reply rules, without saving anything. One model call, not counted as a monthly AI draft; 10 per hour per company (429 with `Retry-After`).",
                "operationId": "v1PreviewAgentVoice",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "reply_voice": {
                                        "properties": {
                                            "preset": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "custom": {
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 600
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    },
                                    "reply_signature": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 120
                                    },
                                    "sample": {
                                        "type": "string",
                                        "default": "positive",
                                        "enum": [
                                            "positive",
                                            "negative"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentVoicePreview"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/login-requests": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List login requests of the review agent",
                "description": "Scope: `reviews:read`. Sites where removal reports the agent decided to file wait for you to connect your account (open requests), with the reviews waiting and the connect link. Once the account is connected the reports are filed without another click.",
                "operationId": "v1ListAgentLoginRequests",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "uuid": {
                                                        "type": "string",
                                                        "format": "uuid"
                                                    },
                                                    "site": {
                                                        "type": "string"
                                                    },
                                                    "site_label": {
                                                        "type": "string"
                                                    },
                                                    "status": {
                                                        "type": "string",
                                                        "enum": [
                                                            "open",
                                                            "connected",
                                                            "manual",
                                                            "canceled"
                                                        ]
                                                    },
                                                    "connect_url": {
                                                        "type": "string",
                                                        "format": "url"
                                                    },
                                                    "waiting": {
                                                        "type": "integer"
                                                    },
                                                    "actions": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        }
                                                    },
                                                    "reminders": {
                                                        "type": "integer"
                                                    },
                                                    "notified_at": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    },
                                                    "created_at": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "nullable": true
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/agent/learnings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "What the review agent learned",
                "description": "Scope: `reviews:read`. What the review agent learned from this business's approvals, edits and rejections (`business.learnings`, the readable style `business.profile`, `business.improvement`), and the patterns it learned across Grades.com (`fleet.learnings`: counts and rates only, never another business's text; `override` says whether this business turned one off). `include_retired=1` also lists retired learnings.",
                "operationId": "v1ListAgentLearnings",
                "parameters": [
                    {
                        "name": "include_retired",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLearnings"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "parameter": "V1AgentLearningPath",
                    "name": "learning",
                    "in": "path",
                    "description": "Uuid of a learning of this business, or of a fleet learning (to turn it off or on for this business).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/agent/learnings/{learning}/accept": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Accept a learning",
                "description": "Scope: `reviews:write`. Confirms a learning: it stays applied and the agent never retires it. For a fleet learning: confirms it for this business (undoes a dismiss).",
                "operationId": "v1AcceptAgentLearning",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLearningDecision"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentLearningPath"
                },
                {
                    "parameter": "V1AgentLearningPath",
                    "name": "learning",
                    "in": "path",
                    "description": "Uuid of a learning of this business, or of a fleet learning (to turn it off or on for this business).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/agent/learnings/{learning}/dismiss": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Dismiss a learning",
                "description": "Scope: `reviews:write`. Turns a learning off for good: it is no longer applied and the agent never learns it again. For a fleet learning: turns it off for this business only.",
                "operationId": "v1DismissAgentLearning",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLearningDecision"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentLearningPath"
                },
                {
                    "parameter": "V1AgentLearningPath",
                    "name": "learning",
                    "in": "path",
                    "description": "Uuid of a learning of this business, or of a fleet learning (to turn it off or on for this business).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/agent/outcomes/summary": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review agent improvement",
                "description": "Scope: `reviews:read`. How the agent is improving: approval-as-written, edit and rejection rates of its reply drafts this month, last month and per week, for this business and across Grades.com (counts only).",
                "operationId": "v1AgentOutcomeSummary",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "business": {
                                                    "$ref": "#/components/schemas/V1AgentOutcomeSummary"
                                                },
                                                "fleet": {
                                                    "$ref": "#/components/schemas/V1AgentOutcomeSummary"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "parameter": "V1AgentLearningPath",
                    "name": "learning",
                    "in": "path",
                    "description": "Uuid of a learning of this business, or of a fleet learning (to turn it off or on for this business).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/agent/actions/{action}/filed": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Mark a removal report as filed",
                "description": "Scope: `reviews:write`. \"I filed it\": records that the removal report of an executed flag action was filed with the site (by hand), on `filed_at` (default now; not in the future). The flag becomes `submitted`; the agent then watches whether the review is removed (`result.report`). 409 when the action is not an executed flag or its flag is closed.",
                "operationId": "v1AgentActionFiled",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "filed_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true
                                    },
                                    "external_reference": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 255
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentAction"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1AgentActionPath"
                },
                {
                    "parameter": "V1AgentLearningPath",
                    "name": "learning",
                    "in": "path",
                    "description": "Uuid of a learning of this business, or of a fleet learning (to turn it off or on for this business).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/alerts/settings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get alert settings",
                "description": "Scope: `reviews:read`. The company's Premium alert preferences. `meta.available` says which alerts its plan includes; an unavailable alert is never sent, whatever the setting.",
                "operationId": "v1GetAlertSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AlertSettings"
                                        },
                                        "meta": {
                                            "properties": {
                                                "available": {
                                                    "properties": {
                                                        "ai_reputation_alerts": {
                                                            "type": "boolean"
                                                        },
                                                        "competitor_alerts": {
                                                            "type": "boolean"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "defaults_on": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update alert settings",
                "description": "Scope: `reviews:write`. Saves the fields sent (at least one). Switching an alert on needs the plan feature (402 `plan_upgrade_required` below Premium); switching off always works.",
                "operationId": "v1UpdateAlertSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "ai_reputation_alerts": {
                                        "type": "boolean"
                                    },
                                    "competitor_alerts": {
                                        "type": "boolean"
                                    },
                                    "competitor_top_n": {
                                        "type": "integer",
                                        "maximum": 20,
                                        "minimum": 1
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AlertSettings"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/alerts": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List alerts",
                "description": "Scope: `reviews:read`. The Premium alerts sent to the company, newest first (history: nothing is removed). Cursor pagination: pass `meta.next_cursor` back as `cursor`. `include_locations=1` on an HQ (group alerts, Premium; 402 below it, 409 `not_an_hq` otherwise) adds the alerts of its locations, each item with its `company` {uuid, name}.",
                "operationId": "v1ListAlerts",
                "parameters": [
                    {
                        "name": "feature",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "ai_reputation",
                                "competitor"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 25,
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "include_locations",
                        "in": "query",
                        "schema": {
                            "type": "boolean",
                            "default": false
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AlertEvent"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/app/ask/businesses": {
            "get": {
                "tags": [
                    "Assistant"
                ],
                "summary": "Ask Grades businesses for the Android app",
                "description": "For the Grades.com Android app (OAuth scope `ask:use`): every business the user can use (a grant limited to some businesses lists only those) with `can_ask` and, when false, `reason` (`disabled` = Ask Grades is switched off, `role` = below Reviewer, `plan` = the plan has no Ask Grades or the month's questions are used up); `meta.suggestions`: short read-only example questions.",
                "operationId": "listAppAskBusinesses",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "required": [
                                                    "uuid",
                                                    "name",
                                                    "can_ask",
                                                    "reason"
                                                ],
                                                "properties": {
                                                    "uuid": {
                                                        "type": "string",
                                                        "format": "uuid"
                                                    },
                                                    "name": {
                                                        "type": "string"
                                                    },
                                                    "can_ask": {
                                                        "type": "boolean"
                                                    },
                                                    "reason": {
                                                        "description": "Why `can_ask` is false; null when true.",
                                                        "type": "string",
                                                        "nullable": true,
                                                        "enum": [
                                                            "disabled",
                                                            "role",
                                                            "plan"
                                                        ]
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "suggestions"
                                            ],
                                            "properties": {
                                                "suggestions": {
                                                    "description": "Short read-only example questions.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "ask:use"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "ask:use"
                ]
            }
        },
        "/v1/app/ask": {
            "post": {
                "tags": [
                    "Assistant"
                ],
                "summary": "Ask Grades from the Android app",
                "description": "For the Grades.com Android app (OAuth scope `ask:use`): one question to Ask Grades, answered synchronously as plain text (no Markdown). Read-only: nothing is posted, saved or changed, and a reply draft is only text in the answer. Errors: 403 `insufficient_scope` / `role_forbidden` (below Reviewer), 404 for a business the user cannot use, 404 `conversation_not_found`, 402 `plan_upgrade_required`, 409 `conversation_full` / `conversation_busy`, 422 `validation_failed`, 429 `assistant_daily_limit` (with `resets_at`) or the per-user rate limit (Retry-After), 503 `assistant_disabled` / `assistant_budget_exhausted`.",
                "operationId": "appAsk",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "company_uuid",
                                    "message"
                                ],
                                "properties": {
                                    "company_uuid": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "message": {
                                        "type": "string",
                                        "maxLength": 2000,
                                        "minLength": 1
                                    },
                                    "conversation_id": {
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK (also for a refused or timed-out turn: the app shows the text as the answer).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "conversation_id",
                                                "answer"
                                            ],
                                            "properties": {
                                                "conversation_id": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "answer": {
                                                    "description": "Plain text (no Markdown).",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "required": [
                                                "usage"
                                            ],
                                            "properties": {
                                                "usage": {
                                                    "description": "The binding allowance: the daily cap or the plan's monthly questions, whichever has fewer left (`limit` null when neither caps).",
                                                    "required": [
                                                        "period",
                                                        "used",
                                                        "limit",
                                                        "resets_at"
                                                    ],
                                                    "properties": {
                                                        "period": {
                                                            "type": "string",
                                                            "enum": [
                                                                "day",
                                                                "month"
                                                            ]
                                                        },
                                                        "used": {
                                                            "type": "integer"
                                                        },
                                                        "limit": {
                                                            "type": "integer",
                                                            "nullable": true
                                                        },
                                                        "resets_at": {
                                                            "type": "string",
                                                            "format": "date-time"
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "ask:use"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "ask:use"
                ]
            }
        },
        "/v1/app/review-pages": {
            "get": {
                "tags": [
                    "ReviewPages"
                ],
                "summary": "Review pages for the Android app",
                "description": "For the Grades.com Android app (OAuth scope `review_pages:read`): the businesses the user can use and their enabled review pages with the public page facts of `info.json` (name, review_url, counter_url, look, accent, on_accent, line, theme, logo_url, sample). Businesses without an enabled page are left out.",
                "operationId": "listAppReviewPages",
                "responses": {
                    "200": {
                        "description": "OK (no `meta`; `Cache-Control: no-store`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AppReviewPagesBusiness"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "review_pages:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "review_pages:read"
                ]
            }
        },
        "/v1/companies/{company}/exports/bigquery": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "BigQuery export settings",
                "description": "Scope: `companies:read`. The company's BigQuery export: its destination, status and last sync, the service account to grant (`roles/bigquery.dataEditor` on the dataset) and the plan's cadences. `configured: false` when none is set up.",
                "operationId": "v1BigQueryExport",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BigQueryExport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Save BigQuery export settings",
                "description": "Scope: `companies:write`, owners and admins. Saves the destination: `project_id`, `dataset_id`, `table_prefix` (default `grades_`), `include_versions` (default true), `all_locations` (an HQ and its locations), `cadence` (`daily`; `hourly` on Premium). A new project, dataset or prefix must be tested again. 400 `invalid_destination` with `errors`; 402 below Pro.",
                "operationId": "v1SaveBigQueryExport",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "description": "Omitted fields keep the saved value (`project_id` and `dataset_id` are required when none is saved yet).",
                                "properties": {
                                    "project_id": {
                                        "description": "Google Cloud project id (6 to 30 lower-case letters, digits or hyphens).",
                                        "type": "string",
                                        "example": "my-project-123"
                                    },
                                    "dataset_id": {
                                        "description": "Letters, digits and underscores.",
                                        "type": "string",
                                        "example": "reviews_data"
                                    },
                                    "table_prefix": {
                                        "description": "At most 32 letters, digits and underscores (default `grades_`).",
                                        "type": "string",
                                        "maxLength": 32
                                    },
                                    "include_versions": {
                                        "type": "boolean",
                                        "default": true
                                    },
                                    "all_locations": {
                                        "type": "boolean",
                                        "default": false
                                    },
                                    "cadence": {
                                        "description": "`hourly` on Premium only.",
                                        "type": "string",
                                        "default": "daily",
                                        "enum": [
                                            "daily",
                                            "hourly"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BigQueryExport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Remove the BigQuery export",
                "description": "Scope: `companies:write`, owners and admins. Stops the export. The tables in the dataset stay.",
                "operationId": "v1DeleteBigQueryExport",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BigQueryExport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/bigquery/test": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Test the BigQuery connection",
                "description": "Scope: `companies:write`, owners and admins. Tests the connection as the service account: reads the dataset and creates the missing tables (idempotent). 409 `dataset_not_found` / `access_denied` (with `iam`, what to grant) / `table_incompatible`; 502 `bigquery_failed`.",
                "operationId": "v1TestBigQueryExport",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BigQueryExport"
                                        },
                                        "meta": {
                                            "properties": {
                                                "tables_created": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/bigquery/sync": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Sync the BigQuery export now",
                "description": "Scope: `companies:write`, owners and admins. \"Sync now\": the export syncs within a few minutes (202). 409 `bigquery_not_tested` before a successful test; 429 `export_limit` (4 an hour).",
                "operationId": "v1SyncBigQueryExport",
                "responses": {
                    "202": {
                        "description": "Accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BigQueryExport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/bigquery/runs": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "BigQuery export runs",
                "description": "Scope: `companies:read`. The last 50 tests and syncs (newest first) with rows written per table and errors.",
                "operationId": "v1BigQueryExportRuns",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/billing/preview": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Preview a plan change",
                "description": "Scope: `companies:read`. What moving to `plan` billed every `interval` would cost, without changing anything: `kind` (upgrade, downgrade, switch_interval, start), `effective` (now, period_end, trial_end), `amount_due_now`, `credit`, `next_invoice` {date, amount} in US dollars, `card_required`, `estimate` (true when computed from the list price instead of a Stripe invoice preview). Session twin: `POST /api/company/{company}/billing/preview`.",
                "operationId": "v1PreviewBillingChange",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BillingChangeRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/BillingChangePreview"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/billing/change-plan": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Change the plan",
                "description": "Scope: `companies:write`, admin role. Changes the plan with the card on file. Without `\"confirm\": true` nothing changes: 409 `confirmation_required` with the `preview`. Upgrades and monthly -> yearly take effect at once (prorated, charged off-session); downgrades at the end of the paid period (`meta.result: scheduled`) unless `immediately`; a business without a subscription starts one (the rest of a free trial is kept, the card is charged when it ends). Without a card on file: 402 `payment_method_required` with `checkout_url` (Stripe Checkout, setup mode) and `pending_change`: the change completes by itself once the card is saved. Asking for the current plan while a downgrade is scheduled cancels it (`meta.result: kept`). Session twin: `POST /api/company/{company}/billing/change-plan`.",
                "operationId": "v1ChangeBillingPlan",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BillingChangeRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Changed (or scheduled); the billing state after the change",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Billing"
                                        },
                                        "meta": {
                                            "properties": {
                                                "result": {
                                                    "type": "string",
                                                    "enum": [
                                                        "changed",
                                                        "scheduled",
                                                        "started",
                                                        "kept"
                                                    ]
                                                },
                                                "change": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/BillingChangePreview"
                                                        },
                                                        {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "enum": [
                                                                null
                                                            ]
                                                        }
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/billing/setup-link": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Link to add a card",
                "description": "Scope: `companies:write`, admin role. A Stripe Checkout page (setup mode) where the business saves a card once; nothing is charged there. A change waiting for a card completes once it is saved; during a no-card trial without one, the trial's plan (monthly) continues when the trial ends. Session twin: `POST /api/company/{company}/billing/setup-link`.",
                "operationId": "v1CreateBillingSetupLink",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                },
                                                "pending_change": {
                                                    "type": "object",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/billing/cancel": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Cancel at period end",
                "description": "Scope: `companies:write`, admin role. Cancels the subscription at the end of the paid period (and any scheduled change); `cancel_at` shows when it ends. 409 `no_subscription` / `already_canceled`. Session twin: `POST /api/company/{company}/billing/cancel`.",
                "operationId": "v1CancelBilling",
                "responses": {
                    "200": {
                        "description": "The billing state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Billing"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/billing/resume": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Resume",
                "description": "Scope: `companies:write`, admin role. Resumes a subscription canceled at the end of the paid period, before it ends. 409 `not_canceled` otherwise. Session twin: `POST /api/company/{company}/billing/resume`.",
                "operationId": "v1ResumeBilling",
                "responses": {
                    "200": {
                        "description": "The billing state",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Billing"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "502": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/billing": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get billing",
                "description": "Scope: `companies:read`. Plan, status, entitlements and usage of the location; same body as the dashboard's billing endpoint. `mode: unconfigured` means billing is not switched on yet and every location has the Pro plan.",
                "operationId": "v1GetBilling",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Billing"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/billing/quote": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Price quote",
                "description": "Scope: `companies:read`. What the business pays on `plan` for `locations` locations (default: the own count of the business, HQ included): base price, the volume bands (graduated), totals, effective price per location, the next band and, for an agency client, the agency price (docs/billing.md \"Volume bands\").",
                "operationId": "v1GetBillingQuote",
                "parameters": [
                    {
                        "name": "plan",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "starter",
                                "pro",
                                "premium"
                            ]
                        }
                    },
                    {
                        "name": "locations",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100000,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/BillingQuote"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/browser-sessions": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List connected review-site accounts",
                "description": "Scope: `companies:read`. The company's connected review-site accounts (never the session itself) with their `state` and latest connect attempt. `meta`: whether browser automation is on, whether connecting is possible now and how (`connect`: methods, the connect service's WebSocket URL, the worker's public key for shared sign-in details), the sites that can be connected with the consent texts per sign-in method and a plain `policy_note`, and `reporting`: the notice that reports are filed with the business's own connected account, and on the platform report sites (Google) with grades.com's own account only when the business has none, with `platform_sites[].available`.",
                "operationId": "v1ListBrowserSessions",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1BrowserSession"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1BrowserSessionListMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Connect a review-site account",
                "description": "Scope: `reviews:write`, company admins. Records the admin's consent (`consent: true` with the current `consent_version`; the text stored is the one for the chosen `method`) and opens a connect attempt with a one-time token (10 minutes). `live` (default): `meta.connect_url` is the live sign-in page (token in the URL fragment) where the owner signs in themselves. `credentials`: `meta.connect_token` + `meta.ws_url` let the dashboard send the sign-in details, encrypted to the worker's key, straight to the worker; they never reach grades.com. A newer attempt cancels the open one. 503 `browser_automation_disabled` while the feature is off, `browser_worker_unavailable` while the connect service is not reachable, `credentials_unavailable` for `credentials` without a worker key; 429 after 10 starts per company per hour.",
                "operationId": "v1ConnectBrowserSession",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "site",
                                    "consent",
                                    "consent_version"
                                ],
                                "properties": {
                                    "site": {
                                        "type": "string",
                                        "example": "yelp"
                                    },
                                    "method": {
                                        "type": "string",
                                        "default": "live",
                                        "enum": [
                                            "live",
                                            "credentials"
                                        ]
                                    },
                                    "consent": {
                                        "type": "boolean",
                                        "example": true
                                    },
                                    "consent_version": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserSession"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1BrowserConnectStartMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/browser-sessions/{session}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Disconnect a review-site account",
                "description": "Scope: `reviews:write`, company admins. Disconnects: the stored session is deleted at once, an open connect attempt is canceled and queued browser jobs are canceled (their agent actions fail and can be approved again). Works while the feature is off.",
                "operationId": "v1RevokeBrowserSession",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/browser-sessions/{session}/connect/{attempt}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a connect attempt",
                "description": "Scope: `companies:read`, only the user who started the attempt. Its status, for polling while the owner signs in (every few seconds).",
                "operationId": "v1GetBrowserConnectAttempt",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserConnectAttempt"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Cancel a connect attempt",
                "description": "Scope: `reviews:write`, the user who started the attempt or a company admin. Cancels an open attempt; the worker closes its browser at its next heartbeat. Idempotent.",
                "operationId": "v1CancelBrowserConnectAttempt",
                "responses": {
                    "204": {
                        "description": "Canceled"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                },
                {
                    "name": "attempt",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/browser-jobs/{job}/evidence": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a browser job's evidence",
                "description": "Scope: `reviews:read`. The screenshots and HTML snippet the browser worker recorded for a job (an agent action's `evidence_url` points here). `url` is a signed link valid for 10 minutes; null when evidence storage is not configured or the evidence is older than the 90-day retention.",
                "operationId": "v1GetBrowserJobEvidence",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserJobEvidence"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "job",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/celebrations": {
            "get": {
                "tags": [
                    "Celebration posts"
                ],
                "summary": "List celebration posts",
                "description": "Scope: `companies:read`. What the company's directory listing can celebrate now (five-star milestone, awards, best-of places, Above and Beyond, grade): per item `key`, `kind`, `title`, `captions`, `hashtags`, `profile_url` and six `variants` (`look` dark | light x `format` square | story | landscape) with `status` (ready | queued | failed | none), `files` (stored MP4 / GIF / PNG URLs when ready) and `links` (stable download links) and `publications` (Google posts of the item: `id`, `state` created | failed | deleted, `published_at`, `search_url`). `meta.listing_id` is null when the company has no directory listing; `meta.publishing` is the Post to Google state (`auto_post_google`, `google.connected`, `google.connect_url`, `min_days_between`).",
                "operationId": "v1ListCelebrations",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1CelebrationItem"
                                            }
                                        },
                                        "meta": {
                                            "description": "`looks`, `formats` and `renderer` are present only when the company has a directory listing.",
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "listing_id": {
                                                    "type": "integer",
                                                    "nullable": true
                                                },
                                                "looks": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "formats": {
                                                    "description": "Pixel size per format (`square`, `story`, `landscape`): `{width, height}`.",
                                                    "type": "object",
                                                    "additionalProperties": {
                                                        "properties": {
                                                            "width": {
                                                                "type": "integer"
                                                            },
                                                            "height": {
                                                                "type": "integer"
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                },
                                                "enabled": {
                                                    "type": "boolean"
                                                },
                                                "renderer": {
                                                    "type": "boolean"
                                                },
                                                "publishing": {
                                                    "$ref": "#/components/schemas/V1CelebrationSettings"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/celebrations/{key}/render": {
            "post": {
                "tags": [
                    "Celebration posts"
                ],
                "summary": "Render a celebration post",
                "description": "Scope: `companies:write`. Queues the variants of one item that are not stored yet (body optional: `looks`, `formats` to limit them); they are recorded within minutes. 202 with the item (`meta.queued`). 429 `celebration_limit` past the listing's daily render cap.",
                "operationId": "v1RenderCelebration",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "looks": {
                                        "description": "Limit to these looks (default: both).",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "dark",
                                                "light"
                                            ]
                                        },
                                        "nullable": true
                                    },
                                    "formats": {
                                        "description": "Limit to these formats (default: all three).",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "square",
                                                "story",
                                                "landscape"
                                            ]
                                        },
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CelebrationItem"
                                        },
                                        "meta": {
                                            "properties": {
                                                "queued": {
                                                    "description": "How many variants were queued now.",
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "key",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    },
                    "example": "milestone:250"
                }
            ]
        },
        "/v1/companies/{company}/celebrations/{key}/publish": {
            "post": {
                "tags": [
                    "Celebration posts"
                ],
                "summary": "Post a celebration to Google",
                "description": "Scope: `companies:write`, owners and admins. Publishes the item as a Google Business Profile post (STANDARD local post: the still frame of the square variant, light by default, the caption without link or hashtags, a \"Learn more\" button to the grades.com profile) through the company's own Google connection. Body: `channel` (google), optional `look` (light | dark), `caption_variant` (1-3), `again` (post once more). 201 with the publication. 409 `google_not_connected` / `google_reconnect_needed` (with `connect_url`), 409 `already_published` (with `publication`), 503 `celebration_image_unavailable`, 502 `google_rejected`.",
                "operationId": "v1PublishCelebration",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "channel": {
                                        "type": "string",
                                        "default": "google",
                                        "enum": [
                                            "google"
                                        ]
                                    },
                                    "look": {
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "dark",
                                            "light"
                                        ]
                                    },
                                    "caption_variant": {
                                        "description": "Which of the item's captions (1 to the number of captions).",
                                        "type": "integer",
                                        "default": 1,
                                        "minimum": 1
                                    },
                                    "again": {
                                        "description": "Post once more although already published.",
                                        "type": "boolean",
                                        "default": false
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Published",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CelebrationPublication"
                                        },
                                        "meta": {
                                            "properties": {
                                                "item_key": {
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "key",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    },
                    "example": "milestone:250"
                }
            ]
        },
        "/v1/companies/{company}/celebrations/publications/{publication}": {
            "delete": {
                "tags": [
                    "Celebration posts"
                ],
                "summary": "Remove a celebration post from Google",
                "description": "Scope: `companies:write`, owners and admins. Removes a celebration post from Google; the removal is recorded as its own publication row (`state` deleted). 404 `publication_not_found`.",
                "operationId": "v1DeleteCelebrationPublication",
                "responses": {
                    "200": {
                        "description": "Removed: the removed post (`state` deleted).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CelebrationPublication"
                                        },
                                        "meta": {
                                            "properties": {
                                                "removal_id": {
                                                    "description": "Id of the publication row recording the removal.",
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "publication",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    },
                    "example": 12
                }
            ]
        },
        "/v1/companies/{company}/celebrations/settings": {
            "get": {
                "tags": [
                    "Celebration posts"
                ],
                "summary": "Celebration post settings",
                "description": "Scope: `companies:read`. `auto_post_google` (default false) and the Google connection: `connected`, `needs_reconnect`, `connect_url`, `min_days_between` (automatic posts) and `next_auto_post_at`.",
                "operationId": "v1CelebrationSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CelebrationSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "Celebration posts"
                ],
                "summary": "Update celebration post settings",
                "description": "Scope: `companies:write`, owners and admins. Body `{\"auto_post_google\": true|false}`: post new awards, five-star milestones and Above and Beyond steps to Google automatically (never grade changes), at most one Google post per company in `min_days_between` days.",
                "operationId": "v1UpdateCelebrationSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "auto_post_google"
                                ],
                                "properties": {
                                    "auto_post_google": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CelebrationSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/chat-hooks": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List chat notifications",
                "description": "Scope: `companies:read`. The chat notifications, with `meta.events` and `meta.kinds`.",
                "operationId": "v1ListChatHooks",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ChatHook"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Add a chat notification",
                "description": "Scope: `companies:write`, owners and admins. Body: `kind` (slack | teams | google_chat), `url` (the channel's https incoming-webhook URL of that app), `events` (default review.created, agent.action.pending, recovery.case.opened), `name`, `rules` (routing rules, see V1ChatHookRule; replaces `events`), `weekly_digest` (true = a summary post on Monday 08:00 local time). 400 `invalid_url` / `invalid_events` / `invalid_rules`, 409 `hook_limit` (10 per company).",
                "operationId": "v1CreateChatHook",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "kind",
                                    "url"
                                ],
                                "properties": {
                                    "kind": {
                                        "type": "string",
                                        "enum": [
                                            "slack",
                                            "teams",
                                            "google_chat"
                                        ]
                                    },
                                    "url": {
                                        "description": "The channel's https incoming-webhook URL of that app.",
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "events": {
                                        "description": "Event keys (`meta.events` of the list); ignored when `rules` are sent.",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "nullable": true
                                    },
                                    "name": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 80
                                    },
                                    "rules": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/components/schemas/V1ChatHookRule"
                                        },
                                        "nullable": true
                                    },
                                    "weekly_digest": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ChatHook"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/chat-hooks/{hook}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Remove a chat notification",
                "description": "Scope: `companies:write`, owners and admins. Removes the chat notification (its message log is kept).",
                "operationId": "v1DeleteChatHook",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "id",
                                                "deleted"
                                            ],
                                            "properties": {
                                                "id": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "deleted": {
                                                    "type": "boolean",
                                                    "enum": [
                                                        true
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Change a chat notification",
                "description": "Scope: `companies:write`, owners and admins. `events`, `rules` (null = back to one list of events), `weekly_digest`, `name`, `active` (true clears the failure state; 409 `chat_disconnected` for a disconnected notification). With rules, change the events through the rules (400 `invalid_events`). Every change of events, rules or the weekly digest is kept in a history.",
                "operationId": "v1UpdateChatHook",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "description": "Only the fields sent change.",
                                "properties": {
                                    "events": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "rules": {
                                        "description": "null = back to one list of events.",
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/components/schemas/V1ChatHookRule"
                                        },
                                        "nullable": true
                                    },
                                    "weekly_digest": {
                                        "type": "boolean"
                                    },
                                    "name": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 80
                                    },
                                    "active": {
                                        "description": "true clears the failure state.",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ChatHook"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "hook",
                    "in": "path",
                    "description": "Chat notification id (uuid).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/chat-hooks/{hook}/test": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Send a test message",
                "description": "Scope: `companies:write`, owners and admins. Posts a test message (with rules: a sample of what the first rule sends); 502 `chat_failed` with the app's answer. When the app answers that the webhook is gone (HTTP 404 / 410, Slack `no_service`, `invalid_token`, `token_revoked` ...) the notification is disconnected: 409 `chat_disconnected` (detail \"Disconnected in Slack: add it again.\", `hook` = the changed notification; the same 409 when it already was, nothing is posted). A transient failure of the app stays 502 `chat_failed`.",
                "operationId": "v1TestChatHook",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "sent": {
                                                    "type": "boolean"
                                                },
                                                "status": {
                                                    "type": "integer",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "hook",
                    "in": "path",
                    "description": "Chat notification id (uuid).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/agency": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "A business's agency",
                "description": "Scope: `companies:read`. The agency the business belongs to (or null), its plan there, the grace period after leaving, and (for the business's admins) the pending requests of agencies.",
                "operationId": "v1GetCompanyAgency",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CompanyAgency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "delete": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Leave the agency",
                "description": "Scope: `companies:write`; the business's admins. The business leaves its agency: it keeps its account and data and the agency plan for the grace period, then pays list price on its own billing.",
                "operationId": "v1LeaveAgency",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CompanyAgency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List companies",
                "description": "Companies the caller is an accepted member of. Scope: `companies:read`. Platform super admins can pass `all=1` to list every company (keyset pages of `limit`, `cursor`, optional `q` search on name, nickname, slug and website, `hq` = an HQ uuid for its locations, and `kind`: tenants by default, `directory` for the unclaimed directory-only businesses, `any` for both).",
                "operationId": "v1ListCompanies",
                "parameters": [
                    {
                        "name": "all",
                        "in": "query",
                        "description": "Super admins only: every company.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "hq",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    },
                    {
                        "name": "kind",
                        "in": "query",
                        "description": "With `all=1`: `customer` (default), `directory` or `any`.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "customer",
                                "directory",
                                "any"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Company"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create a company",
                "description": "Scope: `companies:write`. Creates a location as the dashboard does (slug from the name, default settings, a `direct` source, the 14-day trial). The caller becomes its `super_admin`; platform super admins are not added as members (they reach every company). `hq_company` bills it under an HQ the caller administers.",
                "operationId": "v1CreateCompany",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1CompanyInput"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Company"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/companies/{company}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get company",
                "description": "Scope: `companies:read`. Unknown companies and companies the caller doesn't belong to both answer 404.",
                "operationId": "v1GetCompany",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Company"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a company",
                "description": "Scope: `companies:write`; the caller must be an admin or super admin of the company. Send any of the create fields; `null` clears a field (not `name`). `address` fields are merged.",
                "operationId": "v1UpdateCompany",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1CompanyInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Company"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/sources": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review sources",
                "description": "Connected review sources with their fetch state and review counts. Scope: `companies:read`.",
                "operationId": "v1ListCompanySources",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Source"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Connect a review source",
                "description": "Scope: `reviews:write`. Connects a review site by its business page URL (`yelp`, `bbb`, `thumbtack`, `trustpilot` and the other verified Apify-backed sites; the URL host must match the site) or a G2 product (`g2`: the customer's G2 API `token` and the exact `product_name`). Reviews are fetched by the next scheduled sync. Google and Facebook need OAuth consent in the dashboard (422).",
                "operationId": "v1ConnectSource",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "driver"
                                ],
                                "properties": {
                                    "driver": {
                                        "description": "Also any verified Apify-backed driver (e.g. `tripadvisor`, `google_maps`).",
                                        "type": "string",
                                        "enum": [
                                            "yelp",
                                            "bbb",
                                            "thumbtack",
                                            "trustpilot",
                                            "g2"
                                        ]
                                    },
                                    "url": {
                                        "description": "Business page on the review site. Required except for `g2`.",
                                        "type": "string",
                                        "format": "url"
                                    },
                                    "token": {
                                        "description": "`g2` only: G2 API token.",
                                        "type": "string"
                                    },
                                    "product_name": {
                                        "description": "`g2` only: the product name exactly as on G2.",
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Source"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/stats": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review statistics",
                "description": "Rating distribution and average, overall, per source driver (`by_source`) and per review platform (`by_platform`, display names, drivers of one platform merged). Scope: `reviews:read`.",
                "operationId": "v1GetCompanyStats",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Stats"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/competitors": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Competitor Map",
                "description": "Scope: `companies:read`. The business's competitors, strongest first: `competitor` (listing, brand or external business), `score` 0-1, `signals` (`ai_alternatives`, `ai_co_mentions`, `directory_peer`, `website_similarity`), compare `metrics` (grade, rating, review counts, response rate, AI mention share), `evidence`, `first_seen` / `last_seen`. `signal` = ai|peer|web|all, `limit` 1-50 (default 20). 404 `competitors_disabled` while the competitor map is off.",
                "operationId": "v1ListCompetitors",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 50,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "signal",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "all",
                            "enum": [
                                "ai",
                                "peer",
                                "web",
                                "hub",
                                "all"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Competitor"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1CompetitorReportMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/locations/competitors": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Competitor Map of an HQ and its locations",
                "description": "Scope: `companies:read`. The competitors of an HQ and all of its locations, merged by competitor (strongest score, signals added up); each item has `location_ids` (the uuids of the locations it competes with). Same parameters and shape as `/competitors`. 403 `location_group_access_required`, 409 `not_an_hq` as the other HQ views.",
                "operationId": "v1ListLocationCompetitors",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 50,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "signal",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "all",
                            "enum": [
                                "ai",
                                "peer",
                                "web",
                                "hub",
                                "all"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Competitor"
                                            }
                                        },
                                        "meta": {
                                            "allOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1CompetitorReportMeta"
                                                },
                                                {
                                                    "required": [
                                                        "locations_count"
                                                    ],
                                                    "properties": {
                                                        "locations_count": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            ]
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/competitors/head-to-head": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Competitor Map: head-to-head",
                "description": "Scope: `companies:read`. \"You vs <competitor>\": `you` and `them` (name, logo, profile link, score, grade), `rows` (score, rating, reviews, reviews_12m, response_rate, ai_sentiment, ai_mentioned) with both values, the change since the previous month (`delta_you`, `delta_them`, null without history) and `better` (you|them|tie, null when a value is unknown), `options` (the competitors to pick from). `against` = a competitor `key` of `/competitors` (default: the strongest). Values we do not hold are null. 404 `competitor_not_found` / `no_competitors`.",
                "operationId": "v1CompetitorHeadToHead",
                "parameters": [
                    {
                        "name": "against",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 300
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CompetitorHeadToHead"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/competitors/map": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Competitor Map: map",
                "description": "Scope: `companies:read`. The competitors on a map around the business's own listing: `center`, `you`, `points` (key, name, lat, lng, score, grade, rating, reviews, distance_km, profile_url, logo_url, `in_set`: in the competitor set its profile compares), at most 25, the set first; `unplotted` (competitors without a listing or coordinates, names only). 404 `no_listing` for a business without a listing with coordinates, with `reason` (no_listing: no directory listing; no_location: a listing without coordinates) and `competitors` (how many competitors the list view has).",
                "operationId": "v1CompetitorMap",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CompetitorMap"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/locations/competitors/ranks": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Competitor Map: location ranks of an HQ",
                "description": "Scope: `companies:read`. Per location of the HQ: its rank by Grades.com Score inside its own competitor set (`rank` of `of`), `score`, `grade`, `above` (the businesses ahead of it), `below_count`, `rank_last_month` and `trend` (positive = moved up). `rank: null` with `reason` no_listing|no_set|no_score. 403 `location_group_access_required`, 409 `not_an_hq` as the other HQ views.",
                "operationId": "v1LocationCompetitorRanks",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1LocationCompetitorRank"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "locations_count"
                                            ],
                                            "properties": {
                                                "locations_count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/direct-reviews/settings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get the Reviews on Grades.com settings",
                "description": "Scope: `companies:read`. The settings of Reviews on Grades.com, the form and public list URLs, the wording the form shows for the mode, the limits and the counts by status.",
                "operationId": "v1GetDirectReviewSettings",
                "responses": {
                    "200": {
                        "description": "OK: `data` is the settings.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1DirectReviewSettingsView"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update the Reviews on Grades.com settings",
                "description": "Scope: `companies:write`, company admins. Changes the given fields only (PATCH works the same). A mode change applies to reviews received from then on: reviews already published stay published and counted.",
                "operationId": "v1UpdateDirectReviewSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1DirectReviewSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: `data` is the settings.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1DirectReviewSettingsView"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update the Reviews on Grades.com settings",
                "description": "Same as PUT.",
                "operationId": "v1PatchDirectReviewSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1DirectReviewSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: `data` is the settings.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1DirectReviewSettingsView"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/direct-reviews/{review}/feature": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Feature a curated review",
                "description": "Scope: `companies:write`, company admins. Mode `curated` only: shows the review on the business's Grades.com review list and in its public reviews API, labeled \"Selected by the business\" (never counted in a rating or the grade). `DELETE` takes it off again. Public reviews are always shown; private feedback is never published (409).",
                "operationId": "v1FeatureDirectReview",
                "responses": {
                    "200": {
                        "description": "OK: `data` is the review's Grades.com state.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1DirectReviewState"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Stop featuring a curated review",
                "description": "Takes a featured curated review off the public list.",
                "operationId": "v1UnfeatureDirectReview",
                "responses": {
                    "200": {
                        "description": "OK: `data` is the review's Grades.com state.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1DirectReviewState"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "review",
                    "in": "path",
                    "description": "The review uuid (or the Grades.com review id).",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/direct-reviews/share-packages": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List the share packages of video reviews",
                "description": "Scope: `companies:read`, company owners and admins. The latest share package of each video review that has one (`data`, newest first) and the video reviews whose reviewer allowed sharing that have none yet (`meta.candidates`), with the daily limit.",
                "operationId": "v1ListDirectReviewSharePackages",
                "responses": {
                    "200": {
                        "description": "OK.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "description": "The latest package of each video review that has one, newest first (without `healthcare`, `guidance` and `limits`).",
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SharePackageState"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "candidates": {
                                                    "description": "Video reviews whose reviewer allowed sharing that have no package yet.",
                                                    "type": "array",
                                                    "items": {
                                                        "properties": {
                                                            "review_id": {
                                                                "description": "Uuid of the direct review.",
                                                                "type": "string",
                                                                "format": "uuid"
                                                            },
                                                            "review_row_id": {
                                                                "description": "Uuid of the review row.",
                                                                "type": "string",
                                                                "format": "uuid",
                                                                "nullable": true
                                                            },
                                                            "name": {
                                                                "type": "string"
                                                            },
                                                            "rating": {
                                                                "type": "integer"
                                                            },
                                                            "published_at": {
                                                                "type": "string",
                                                                "format": "date-time",
                                                                "nullable": true
                                                            },
                                                            "has_package": {
                                                                "type": "boolean"
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                },
                                                "healthcare": {
                                                    "type": "boolean"
                                                },
                                                "guidance": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "per_day": {
                                                    "type": "integer"
                                                },
                                                "used_today": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/direct-reviews/{review}/share-package": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get the share package of a video review",
                "description": "Scope: `companies:read`, company owners and admins. Whether the reviewer allowed sharing, whether a package may be made now (`eligible`, else `reason`: no_video, no_consent, withdrawn, not_published, video_hidden), the latest package (files: `vertical` 1080x1920 MP4, `square` 1080x1080 MP4, `cover` PNG; links of a healthcare business are signed and expire after an hour) and the business's responsibilities (`guidance`).",
                "operationId": "v1GetDirectReviewSharePackage",
                "responses": {
                    "200": {
                        "description": "OK.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SharePackageState"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Prepare the share package of a video review",
                "description": "Scope: `companies:write`, company owners and admins. Queues the share package of a video review whose reviewer allowed sharing (202; rendered within a few minutes, poll the GET). A ready package is returned as it is (200) unless `again` is true. Refusals: 409 with `code` no_video, no_consent, withdrawn, not_published or video_hidden; 429 `daily_limit` (10 a day per business); 503 `renderer_unavailable`.",
                "operationId": "v1CreateDirectReviewSharePackage",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "again": {
                                        "description": "Render a new package even when one is ready.",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "A ready package (unchanged).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SharePackageState"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Queued.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SharePackageState"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "review",
                    "in": "path",
                    "description": "The review uuid (or the Grades.com review id).",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/directory/listings/{id}": {
            "get": {
                "tags": [
                    "v1 directory"
                ],
                "summary": "Directory listing with grade and how to improve it",
                "description": "Scope: `directory:read`. A directory listing as its public profile shows it, with the latest Grades.com Score (`score`: parts and items with points, as stored by the score version that wrote it) and `improve` (items with headroom, biggest possible gain first, with advice; the points each grade above the current one needs; the best-of entry requirements it fails), its current best-of placements, the badge and the claim link. The claim state only for super admins and the listing's own team. 404 `listing_merged` (+ `merged_into`) for a merged listing, `directory_not_public` during staging for others, `directory_disabled` while the API is off.",
                "operationId": "v1DirectoryListing",
                "responses": {
                    "200": {
                        "description": "OK: `data` the listing; `meta` source, directory_url, staging, disclosure.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1DirectoryListing"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1DirectoryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "directory:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "directory:read"
                ]
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "Public listing id (from 10000).",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/directory/listings/{id}/claim": {
            "get": {
                "tags": [
                    "v1 directory"
                ],
                "summary": "Claiming a directory listing",
                "description": "Scope: `directory:read`. What claiming the listing takes: the listing, the verification methods (`email` at the website's domain, `review` by the moderators), the claim link on my.grades.com, whether the caller can already edit it, the caller's own claims of it (`my_claims`) and, for super admins and its own team, the claim state. Claims are started and verified only on my.grades.com.",
                "operationId": "v1DirectoryListingClaim",
                "responses": {
                    "200": {
                        "description": "OK: `data` {listing, methods, claim_url, can_edit, state?, my_claims}.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "listing": {
                                                    "$ref": "#/components/schemas/V1DirectoryClaimListing"
                                                },
                                                "methods": {
                                                    "$ref": "#/components/schemas/V1DirectoryClaimMethods"
                                                },
                                                "claim_url": {
                                                    "type": "string",
                                                    "format": "url"
                                                },
                                                "can_edit": {
                                                    "type": "boolean"
                                                },
                                                "state": {
                                                    "description": "Only for super admins and the listing's own team.",
                                                    "type": "string",
                                                    "enum": [
                                                        "unclaimed",
                                                        "claimed",
                                                        "managed"
                                                    ]
                                                },
                                                "my_claims": {
                                                    "description": "The caller's own claims of the listing, newest first (at most 20).",
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/V1DirectoryClaim"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1DirectoryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "directory:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "directory:read"
                ]
            },
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "Public listing id (from 10000).",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/companies/{company}/directory": {
            "get": {
                "tags": [
                    "v1 directory"
                ],
                "summary": "Directory listings of a company",
                "description": "Scope: `directory:read`. The directory listings of a company the caller belongs to (merged ones left out), each as `GET /v1/directory/listings/{id}` with the claim state.",
                "operationId": "v1CompanyDirectory",
                "responses": {
                    "200": {
                        "description": "OK: `data[]` listings; `meta` count + the directory meta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1DirectoryListing"
                                            }
                                        },
                                        "meta": {
                                            "allOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1DirectoryMeta"
                                                },
                                                {
                                                    "properties": {
                                                        "count": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            ]
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "directory:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "directory:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/sources/discover": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Discover review sources",
                "description": "Scope: `reviews:write`. Looks for the company's profiles on review sites: links on its website, Google Places (when configured) and `site:` Google searches through Apify (when configured; one actor run). Stores and returns candidates with a confidence and evidence. Costs up to `DISCOVERY_MAX_COST_USD` (0.50) and can take up to about two minutes. Without an Apify token only the website and Places are checked (`meta.mode: no_search`).",
                "operationId": "v1DiscoverSources",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "description": "Defaults to the company name.",
                                        "type": "string"
                                    },
                                    "website": {
                                        "description": "Defaults to the company website.",
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string"
                                    },
                                    "state": {
                                        "type": "string"
                                    },
                                    "drivers": {
                                        "description": "Only these sites (default: all known).",
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SourceCandidate"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/sources/candidates": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List source candidates",
                "description": "Scope: `companies:read`. Stored candidates, newest first; `status` (`new`, `accepted`, `rejected`), `driver`, `limit` (1-100, default 50), `cursor`.",
                "operationId": "v1ListSourceCandidates",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SourceCandidate"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/sources/candidates/{candidate}/accept": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Accept a source candidate",
                "description": "Scope: `reviews:write`. Connects the candidate as a review source through the same path as `POST /sources` (URL host validation, plan limits). Optional body `{\"url\": \"...\"}` overrides the URL. Other `new` candidates of the same driver are rejected. 422 when the site cannot be connected (`connectable: false`), the driver is already connected, or the candidate was decided.",
                "operationId": "v1AcceptSourceCandidate",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "url": {
                                        "description": "Overrides the candidate's URL.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 2048
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "candidate",
                                                "source"
                                            ],
                                            "properties": {
                                                "candidate": {
                                                    "$ref": "#/components/schemas/V1SourceCandidate"
                                                },
                                                "source": {
                                                    "$ref": "#/components/schemas/V1Source"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "candidate",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/companies/{company}/sources/candidates/{candidate}/reject": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Reject a source candidate",
                "description": "Scope: `reviews:write`. Marks the candidate rejected; later discovery runs keep it rejected.",
                "operationId": "v1RejectSourceCandidate",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SourceCandidate"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "candidate",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/companies/{company}/email-trigger": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Show the email trigger",
                "description": "Scope: `companies:read`, company admins. The address (null before one is created), its settings and 30-day counts; `meta.domain` is the receiving domain. 404 while the email trigger is off.",
                "operationId": "v1ShowEmailTrigger",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "oneOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1EmailTriggerAddress"
                                                },
                                                {
                                                    "type": "object",
                                                    "nullable": true,
                                                    "enum": [
                                                        null
                                                    ]
                                                }
                                            ]
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create the email trigger address",
                "description": "Scope: `companies:write`, company admins, plan feature `review_requests`. Creates the business's private address (200 with the existing one when it has one), optionally with settings.",
                "operationId": "v1CreateEmailTrigger",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1EmailTriggerSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1EmailTriggerAddress"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Change the email trigger settings",
                "description": "Scope: `companies:write`, company admins. Pause / resume (`status`), allowed sender domains (not free mail providers), delay (`delay_days` or `delay_minutes`, default 2 days), daily cap, campaign and location. Omitted fields stay; null resets to the default.",
                "operationId": "v1UpdateEmailTrigger",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1EmailTriggerSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1EmailTriggerAddress"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/email-trigger/regenerate": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Regenerate the email trigger address",
                "description": "Scope: `companies:write`, company admins, plan feature `review_requests`. A new address; the old one stops working at once. Settings carry over.",
                "operationId": "v1RegenerateEmailTrigger",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1EmailTriggerAddress"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/email-trigger/events": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List email trigger events",
                "description": "Scope: `companies:read`, company admins. The latest outcomes (newest first, `limit` 1-100, default 50): accepted (a request was scheduled), existing, pending, or skipped with a reason. Addresses are masked.",
                "operationId": "v1ListEmailTriggerEvents",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 100,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1EmailTriggerEvent"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review exports",
                "description": "Scope: `reviews:read`. The company's Google Sheets exports (newest first), with `meta.google` (the caller's own Google connection), `meta.columns` and `meta.limits`.",
                "operationId": "v1ListExports",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewExport"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/reviews.csv": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Export reviews as CSV",
                "description": "Scope: `reviews:read`. The reviews as a CSV file (UTF-8 with a byte order mark, comma separated, newest first, at most 50,000 rows; `X-Export-Rows`, `X-Export-Truncated`). Filters (all optional, the dashboard list's): `start_date` / `end_date` (YYYY-MM-DD), `source_drivers` (comma-separated site keys), `min_rating` / `max_rating` (1-5), `has_company_response` (true / false), `min_length` / `max_length`, `s` (or `search`), `removed` (`exclude` | `only`; omitted = both). `columns` (comma-separated: review_id, date, site, rating, reviewer, text, reply, replied_at, location, url, removed, removed_at, hidden, edited_at, tags, sentiment, language, translation, reply_status, replied_by, origin, arrival, photos, videos). `all_locations=1` on an HQ exports every location (needs access to all of them). `include_versions=1` adds the columns Version, Changed at and Change, and after each review one row per earlier version from the review archive (edited, removed from its site, restored; oldest first). The plan's history window applies. Without `columns`: review_id and the default columns. 60 files per company per day (429 `export_limit`).",
                "operationId": "v1ExportReviewsCsv",
                "responses": {
                    "200": {
                        "description": "CSV file",
                        "content": {
                            "text/csv": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/reviews.xlsx": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Export reviews as Excel",
                "description": "Scope: `reviews:read`. The reviews as an Excel workbook (sheet \"Reviews\", header row frozen, dates as dates in UTC, ratings and counts as numbers, Removed / Hidden as TRUE / FALSE; text is never a formula). Same filters, columns and headers as the CSV. The file is built before it is sent: above 10,000 reviews 409 `export_too_large` (use `POST .../exports/files`, built in the background and e-mailed). Filters (all optional, the dashboard list's): `start_date` / `end_date` (YYYY-MM-DD), `source_drivers` (comma-separated site keys), `min_rating` / `max_rating` (1-5), `has_company_response` (true / false), `min_length` / `max_length`, `s` (or `search`), `removed` (`exclude` | `only`; omitted = both). `columns` (comma-separated: review_id, date, site, rating, reviewer, text, reply, replied_at, location, url, removed, removed_at, hidden, edited_at, tags, sentiment, language, translation, reply_status, replied_by, origin, arrival, photos, videos). `all_locations=1` on an HQ exports every location (needs access to all of them). `include_versions=1` adds the columns Version, Changed at and Change, and after each review one row per earlier version from the review archive (edited, removed from its site, restored; oldest first). The plan's history window applies. Counts as one of the day's exports (429 `export_limit`).",
                "operationId": "v1ExportReviewsXlsx",
                "responses": {
                    "200": {
                        "description": "Excel file",
                        "content": {
                            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/files": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List background export files",
                "description": "Scope: `reviews:read`. The caller's own background exports of this location (newest first, at most 20): status `queued`, `building`, `ready` (the link was e-mailed), `failed` or `expired`. The download link is only in the e-mail.",
                "operationId": "v1ListExportFiles",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewFileExport"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Export reviews as a file by e-mail",
                "description": "Scope: `reviews:read`. Builds the reviews as a file in the background and e-mails the caller a download link (works for 7 days, at most 20 downloads, while the caller still has access). For exports too big to download at once. Body: `format` (`csv` | `xlsx`), `filters`, `columns`, `all_locations`, `include_versions` (as the download routes). 202 with the export (`status` `queued`); usually ready within a few minutes. Counts as one of the day's exports (429 `export_limit`); at most 3 being prepared per person (429 `export_busy`).",
                "operationId": "v1CreateExportFile",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ReviewExportRequest"
                                    },
                                    {
                                        "properties": {
                                            "format": {
                                                "type": "string",
                                                "default": "csv",
                                                "enum": [
                                                    "csv",
                                                    "xlsx"
                                                ]
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewFileExport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/reviews.csv/link": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Download link of a CSV export",
                "description": "Scope: `reviews:read`. A one-time download link of the CSV (works once, for 10 minutes, without a login), for clients that cannot save a file (AI assistants). Body: `filters` (as the CSV route), `columns`, `all_locations`, `include_versions`. Counts as one of the day's CSV exports.",
                "operationId": "v1ExportReviewsCsvLink",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewExportRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "url": {
                                                    "type": "string",
                                                    "format": "url"
                                                },
                                                "expires_at": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                },
                                                "rows": {
                                                    "type": "integer"
                                                },
                                                "truncated": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/sheets": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Export reviews to Google Sheets",
                "description": "Scope: `companies:write`. Creates a Google Sheets spreadsheet with the reviews in the caller's own Google Drive (Review ID first). Body: `filters`, `columns`, `sync` (`none` | `hourly` | `daily`), `title`, `all_locations`, `include_versions` (earlier versions as extra rows; a sync keeps them by Review ID and Version), `layout` (`reporting`: also the tabs Daily metrics and By platform, one row per day and location, for reporting tools' Google Sheets sources; rewritten on every sync). 409 `google_not_connected` / `google_reconnect_needed` carry `connect_url` (opened in a browser signed in to the dashboard); 429 `export_limit` (10 a day per company); 502 `google_failed`.",
                "operationId": "v1ExportReviewsSheets",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ReviewExportRequest"
                                    },
                                    {
                                        "properties": {
                                            "sync": {
                                                "type": "string",
                                                "default": "none",
                                                "enum": [
                                                    "none",
                                                    "hourly",
                                                    "daily"
                                                ]
                                            },
                                            "title": {
                                                "description": "The spreadsheet title (at most 100 characters kept).",
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "layout": {
                                                "description": "`reviews` (default): the Reviews sheet only; `reporting`: also the Daily metrics and By platform tabs.",
                                                "type": "string",
                                                "nullable": true,
                                                "enum": [
                                                    "reviews",
                                                    "reporting"
                                                ]
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewExport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/exports/{export}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Stop a Google Sheets sync",
                "description": "Scope: `companies:write`. Stops a Google Sheets export's sync (the sheet stays in its owner's Drive). The person who created it, or an owner / admin (403 `role_forbidden`).",
                "operationId": "v1StopExport",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewExport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "export",
                    "in": "path",
                    "description": "Export id (uuid).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/google-grant": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Google connection for Sheets",
                "description": "Scope: `reviews:read`. The caller's own Google connection for Google Sheets exports.",
                "operationId": "v1GoogleGrant",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1GoogleGrant"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Disconnect Google for Sheets",
                "description": "Scope: `companies:write`. Disconnects the caller's Google connection (Google is asked to revoke it) and stops the syncs of the sheets they made; the sheets stay in their Drive.",
                "operationId": "v1DeleteGoogleGrant",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1GoogleGrant"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/feeds": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review feed addresses",
                "description": "Scope: `companies:read`. The review feed addresses of this company: `rss`, `atom`, `json` (JSON Feed 1.1) and `summary` (rating summary JSON), plus `all_locations` variants for an HQ. Pass `key` (a publishable key of this company, else 404) to get working addresses; without it they carry `gk_pub_YOUR_KEY`. `meta.keys` lists the active publishable keys by prefix (the full key is shown only once, when it is created).",
                "operationId": "v1Feeds",
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "description": "A publishable key of this company to fill into the addresses.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` holds the addresses, `meta` the options and the active keys.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1FeedUrls"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1FeedsMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/hub/clients/{hubClientId}/companies": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Companies of a Hub client (Hub MCP)",
                "description": "Ability: `hub:client-read`. The Grades companies linked to a Hub client by identity only: Hub-provisioned (`companies.hub_client_id`) or the company of a directory listing the Hub pushed for that client (adopted tenant or directory-only). Offboarded Hub locations are listed with `status: offboarded`. Never matched by name or domain. 404 `not_found` for an unknown client.",
                "operationId": "v1HubClientCompanies",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientCompany"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1HubClientCompany"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1HubClientMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:client-read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/HubClientId"
                }
            ]
        },
        "/v1/hub/clients/{hubClientId}/reviews-summary": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Reviews summary of a Hub client (Hub MCP)",
                "description": "Ability: `hub:client-read`. Review counts of the companies of the client (or the one in `company`) for a period: all-time total and average, new reviews in the period and their average, the previous period of the same length, reply rate (`response_rate`: share of the new reviews of the period answered on the site or from Grades), unanswered 1-3 star reviews, star distribution, per site and per company. Reviews removed from their site are left out. Periods are calendar days in the timezone of the first company.",
                "operationId": "v1HubClientReviewsSummary",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientCompany"
                    },
                    {
                        "name": "period",
                        "in": "query",
                        "description": "Ignored when `from` is given.",
                        "schema": {
                            "type": "string",
                            "default": "last_30_days",
                            "enum": [
                                "last_7_days",
                                "last_30_days",
                                "last_90_days",
                                "last_12_months",
                                "this_month",
                                "last_month"
                            ]
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "description": "Inclusive; default today. At most 366 days from `from`.",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` {period, totals, by_site, companies}; `meta` V1HubClientMeta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "period": {
                                                    "properties": {
                                                        "key": {
                                                            "type": "string",
                                                            "enum": [
                                                                "last_7_days",
                                                                "last_30_days",
                                                                "last_90_days",
                                                                "last_12_months",
                                                                "this_month",
                                                                "last_month",
                                                                "custom"
                                                            ]
                                                        },
                                                        "from": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "to": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "previous_from": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "previous_to": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "timezone": {
                                                            "type": "string",
                                                            "example": "America/New_York"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "totals": {
                                                    "$ref": "#/components/schemas/V1HubClientReviewMetrics"
                                                },
                                                "by_site": {
                                                    "description": "One row per review platform (`site` = `platform`; `sources` the drivers merged).",
                                                    "type": "array",
                                                    "items": {
                                                        "properties": {
                                                            "site": {
                                                                "type": "string",
                                                                "nullable": true
                                                            },
                                                            "platform": {
                                                                "type": "string",
                                                                "nullable": true
                                                            },
                                                            "sources": {
                                                                "type": "array",
                                                                "items": {
                                                                    "type": "string"
                                                                }
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "nullable": true
                                                            },
                                                            "reviews_total": {
                                                                "type": "integer",
                                                                "nullable": true
                                                            },
                                                            "rating_average": {
                                                                "type": "number",
                                                                "nullable": true
                                                            },
                                                            "new_reviews": {
                                                                "type": "integer",
                                                                "nullable": true
                                                            },
                                                            "new_rating_average": {
                                                                "type": "number",
                                                                "nullable": true
                                                            },
                                                            "response_rate": {
                                                                "type": "number",
                                                                "nullable": true
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                },
                                                "companies": {
                                                    "description": "Per company: the brief company, its metrics and its review-site connections.",
                                                    "type": "array",
                                                    "items": {
                                                        "allOf": [
                                                            {
                                                                "properties": {
                                                                    "company": {
                                                                        "oneOf": [
                                                                            {
                                                                                "$ref": "#/components/schemas/V1HubClientCompanyBrief"
                                                                            },
                                                                            {
                                                                                "type": "object",
                                                                                "nullable": true,
                                                                                "enum": [
                                                                                    null
                                                                                ]
                                                                            }
                                                                        ]
                                                                    },
                                                                    "connections": {
                                                                        "properties": {
                                                                            "status": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "ok",
                                                                                    "attention"
                                                                                ]
                                                                            },
                                                                            "google": {
                                                                                "type": "string",
                                                                                "enum": [
                                                                                    "connected",
                                                                                    "reconnect",
                                                                                    "not_connected"
                                                                                ]
                                                                            },
                                                                            "issues": {
                                                                                "type": "array",
                                                                                "items": {
                                                                                    "properties": {
                                                                                        "platform": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "name": {
                                                                                            "type": "string"
                                                                                        },
                                                                                        "state": {
                                                                                            "type": "string",
                                                                                            "enum": [
                                                                                                "reconnect",
                                                                                                "failing",
                                                                                                "not_connected"
                                                                                            ]
                                                                                        }
                                                                                    },
                                                                                    "type": "object"
                                                                                }
                                                                            }
                                                                        },
                                                                        "type": "object"
                                                                    }
                                                                },
                                                                "type": "object"
                                                            },
                                                            {
                                                                "$ref": "#/components/schemas/V1HubClientReviewMetrics"
                                                            }
                                                        ]
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1HubClientMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:client-read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/HubClientId"
                }
            ]
        },
        "/v1/hub/clients/{hubClientId}/new-reviews": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "New reviews of a Hub client (Hub MCP)",
                "description": "Ability: `hub:client-read`. The latest reviews of the companies of the client (or the one in `company`), newest first: site, rating, date, author display name, a text excerpt (at most 500 characters) and the reply state. Reviews removed from their site and reviews older than the history window of the plan are left out (as on the public reviews API). The text of a site whose terms allow rating and count only (Yelp: `aggregate` in the review display policy) is withheld: `text: null`, `text_withheld: true`.",
                "operationId": "v1HubClientNewReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientCompany"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 50,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "description": "Only reviews published on or after this date.",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "min_rating",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 5,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "max_rating",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 5,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1HubClientReview"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1HubClientMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:client-read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/HubClientId"
                }
            ]
        },
        "/v1/hub/clients/{hubClientId}/ai-reputation": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "AI reputation of a Hub client (Hub MCP)",
                "description": "Ability: `hub:client-read`. What AI assistants say about each company of the client (or the one in `company`): per company the payload of `GET /v1/companies/{company}/radar/ai-perception` (`summary` per engine of the latest run, `measures` Mentioned / Sentiment / Rating accuracy / Review sites cited, `probes` of the latest runs, `history`). With several companies `rollup.measures` counts every company x engine (e.g. \"mentioned in 7 of 12\"). Empty `summary` = no probe has run yet.",
                "operationId": "v1HubClientAiReputation",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientCompany"
                    },
                    {
                        "name": "engine",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "gemini",
                                "openai",
                                "perplexity",
                                "anthropic"
                            ]
                        }
                    },
                    {
                        "name": "probes",
                        "in": "query",
                        "description": "`0` leaves the probes (full answers) out.",
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` {companies: [{company, summary, measures, probes, history, last_run_at}], rollup}.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "companies": {
                                                    "description": "Per company: the payload of `GET /v1/companies/{company}/radar/ai-perception` (`probes` empty with `probes=0`) plus `company` and `last_run_at`.",
                                                    "type": "array",
                                                    "items": {
                                                        "allOf": [
                                                            {
                                                                "properties": {
                                                                    "company": {
                                                                        "$ref": "#/components/schemas/V1HubClientCompanyBrief"
                                                                    },
                                                                    "last_run_at": {
                                                                        "type": "string",
                                                                        "format": "date-time",
                                                                        "nullable": true
                                                                    }
                                                                },
                                                                "type": "object"
                                                            },
                                                            {
                                                                "$ref": "#/components/schemas/V1AiPerception"
                                                            }
                                                        ]
                                                    }
                                                },
                                                "rollup": {
                                                    "description": "With several companies: every company x engine counted (no `facts`); else null.",
                                                    "properties": {
                                                        "companies": {
                                                            "type": "integer"
                                                        },
                                                        "measures": {
                                                            "$ref": "#/components/schemas/V1AiReputationMeasures"
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "allOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1HubClientMeta"
                                                },
                                                {
                                                    "properties": {
                                                        "engines_configured": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "gemini",
                                                                    "openai",
                                                                    "perplexity",
                                                                    "anthropic"
                                                                ]
                                                            }
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            ]
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:client-read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/HubClientId"
                }
            ]
        },
        "/v1/hub/clients/{hubClientId}/competitors": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Competitor map of a Hub client (Hub MCP)",
                "description": "Ability: `hub:client-read`. The Competitor Map (docs/competitors.md) of the company of the client in `company`, or of all its companies together (the HQ view of `GET /v1/companies/{company}/locations/competitors`): same `data` items and `meta` (signals, history) as `GET /v1/companies/{company}/competitors`, plus the client meta. 404 `competitors_disabled` while the competitor map is off.",
                "operationId": "v1HubClientCompetitors",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientCompany"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 50,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "signal",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "all",
                            "enum": [
                                "ai",
                                "peer",
                                "web",
                                "hub",
                                "all"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` competitors; `meta` the report meta + V1HubClientMeta + `companies`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Competitor"
                                            }
                                        },
                                        "meta": {
                                            "allOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1CompetitorReportMeta"
                                                },
                                                {
                                                    "$ref": "#/components/schemas/V1HubClientMeta"
                                                },
                                                {
                                                    "properties": {
                                                        "companies": {
                                                            "type": "array",
                                                            "items": {
                                                                "$ref": "#/components/schemas/V1HubClientCompanyBrief"
                                                            }
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            ]
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:client-read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/HubClientId"
                }
            ]
        },
        "/v1/hub/clients/{hubClientId}/directory": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Directory grades of a Hub client (Hub MCP)",
                "description": "Ability: `hub:client-read`. The grades.com directory listings of the companies of the client (or the one in `company`): per listing the profile URL, the Grades.com Score (`score`: grade, parts and items), `improve` (items with headroom, biggest possible gain first, the points each better grade needs, best-of entry gaps), the grade badge (`svg_url`, `snippet`, `available`) and the current best-of placements. A company without a listing has `listings: []`. `meta` adds the directory disclosure.",
                "operationId": "v1HubClientDirectory",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientCompany"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` {companies: [{company, listings}]}; `meta` V1HubClientMeta + directory meta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "companies": {
                                                    "type": "array",
                                                    "items": {
                                                        "properties": {
                                                            "company": {
                                                                "$ref": "#/components/schemas/V1HubClientCompanyBrief"
                                                            },
                                                            "listings": {
                                                                "type": "array",
                                                                "items": {
                                                                    "properties": {
                                                                        "id": {
                                                                            "type": "integer"
                                                                        },
                                                                        "name": {
                                                                            "type": "string"
                                                                        },
                                                                        "city": {
                                                                            "type": "string",
                                                                            "nullable": true
                                                                        },
                                                                        "state": {
                                                                            "type": "string",
                                                                            "nullable": true
                                                                        },
                                                                        "status": {
                                                                            "type": "string",
                                                                            "example": "active"
                                                                        },
                                                                        "published": {
                                                                            "type": "boolean"
                                                                        },
                                                                        "claim_state": {
                                                                            "type": "string",
                                                                            "enum": [
                                                                                "unclaimed",
                                                                                "claimed",
                                                                                "managed"
                                                                            ]
                                                                        },
                                                                        "profile_url": {
                                                                            "type": "string",
                                                                            "format": "url",
                                                                            "nullable": true
                                                                        },
                                                                        "score": {
                                                                            "oneOf": [
                                                                                {
                                                                                    "$ref": "#/components/schemas/V1DirectoryScore"
                                                                                },
                                                                                {
                                                                                    "type": "object",
                                                                                    "nullable": true,
                                                                                    "enum": [
                                                                                        null
                                                                                    ]
                                                                                }
                                                                            ]
                                                                        },
                                                                        "improve": {
                                                                            "oneOf": [
                                                                                {
                                                                                    "$ref": "#/components/schemas/V1DirectoryImprove"
                                                                                },
                                                                                {
                                                                                    "type": "object",
                                                                                    "nullable": true,
                                                                                    "enum": [
                                                                                        null
                                                                                    ]
                                                                                }
                                                                            ]
                                                                        },
                                                                        "badge": {
                                                                            "$ref": "#/components/schemas/V1HubDirectoryBadge"
                                                                        },
                                                                        "rankings": {
                                                                            "type": "array",
                                                                            "items": {
                                                                                "$ref": "#/components/schemas/V1DirectoryPlacement"
                                                                            }
                                                                        }
                                                                    },
                                                                    "type": "object"
                                                                }
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "allOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1HubClientMeta"
                                                },
                                                {
                                                    "$ref": "#/components/schemas/V1DirectoryMeta"
                                                }
                                            ]
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:client-read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/HubClientId"
                }
            ]
        },
        "/v1/companies/{company}/insights": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review Insights",
                "description": "Scope: `reviews:read`. What the stored data says about the business for a period (`from`/`to`, dates in the company's timezone, inclusive; default the last 90 days, at most 731) against the previous period of the same length (`compare=prev`, the default; `none` leaves every `prev`/`trend` null): `period` totals, `volume` per month, `by_site`, `sentiment` (AI answers and 1-2 star share per month), `response` (rate, median hours to the first reply), `themes` and `attributes` (from the directory listing's stored themes and attribute scores; `themes.available` false without them), `removed`, `locations` (an HQ with locations, for a caller who sees all of them; else null) and `highlights` (3-5 sentences written by fixed rules). No model is called.",
                "operationId": "v1ReviewInsights",
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "compare",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "prev",
                            "enum": [
                                "prev",
                                "none"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewInsights"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReviewInsightsMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/integrations": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List job-done integrations",
                "description": "Scope: `companies:read`, company admins. Every job-done platform with its availability and the company's connection (account, settings, last event, 30-day counts).",
                "operationId": "v1ListIntegrations",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Integration"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/integrations/{platform}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Show a job-done integration",
                "description": "Scope: `companies:read`, company admins. One platform, with the connection's 20 latest events.",
                "operationId": "v1ShowIntegration",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Integration"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Connect a job-done integration with API keys",
                "description": "Scope: `companies:write`, company admins, plan feature `review_requests`. API-key platforms (Housecall Pro: `api_key`, `webhook_signing_secret`; Open Dental: `customer_key`): checks the keys with the platform (422 when refused) and stores them encrypted. Sending only some fields keeps the others. Optional settings in the same body. OAuth platforms answer 409 `oauth_platform` (use the connect link).",
                "operationId": "v1ConnectIntegration",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1IntegrationConnectInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Connected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Integration"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Disconnect a job-done integration",
                "description": "Scope: `companies:write`, company admins. Disconnects: tells the platform (best effort), forgets the credentials, keeps the connection's history. Requests already scheduled are not canceled.",
                "operationId": "v1DisconnectIntegration",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a job-done integration",
                "description": "Scope: `companies:write`, company admins. Settings: `campaign` (uuid or `default`), `delay_minutes` (0-43200; null = the campaign's first step), `trigger_kinds`, `min_value` (platforms with amounts), `sms_enabled` + `sms_consent_text` (only platforms with a text-message opt-in field; the wording your customers agree to there), `paused`.",
                "operationId": "v1UpdateIntegration",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1IntegrationSettingsInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Integration"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1IntegrationPlatformPath"
                }
            ]
        },
        "/v1/companies/{company}/integrations/{platform}/connect-link": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Connect link of a job-done integration",
                "description": "Scope: `companies:write`, company admins, plan feature `review_requests`. OAuth platforms: a single-use link (15 minutes) the person opens in a browser to sign in on the platform; grades.com stores the connection and sends the browser back to the dashboard. Clio takes `region` (us, eu, ca, au). API-key platforms: the fields to send to `POST .../integrations/{platform}` and the requirements.",
                "operationId": "v1IntegrationConnectLink",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "region": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1IntegrationConnectLink"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1IntegrationPlatformPath"
                }
            ]
        },
        "/v1/companies/{company}/integrations/{platform}/test": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Test a job-done integration",
                "description": "Scope: `companies:write`, company admins. Checks the connection with the platform and runs a made-up completed job through the mapping and the campaign checks. Nothing is created or sent.",
                "operationId": "v1TestIntegration",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1IntegrationTest"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1IntegrationPlatformPath"
                }
            ]
        },
        "/v1/integrations/presets": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List integration presets",
                "description": "Every API-key integration (Zapier, Make, n8n, Google Sheets, Looker Studio, WordPress): the key it needs (type, scopes, all businesses or one), the paste steps, and the setup guide (listing status, install link, steps with who does each: agent, user or agent_or_user). Any credential. `meta.reports_url_keys_enabled`: whether reporting URL keys (\"Usable in a URL\", docs/reports.md) can be created and used right now.",
                "operationId": "listIntegrationPresets",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1IntegrationPreset"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count",
                                                "version",
                                                "reports_url_keys_enabled"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "version": {
                                                    "type": "integer"
                                                },
                                                "reports_url_keys_enabled": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            }
        },
        "/v1/integrations/presets/{integration}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get integration preset",
                "description": "One integration preset with its setup guide.",
                "operationId": "getIntegrationPreset",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1IntegrationPreset"
                                        },
                                        "meta": {
                                            "required": [
                                                "version",
                                                "reports_url_keys_enabled"
                                            ],
                                            "properties": {
                                                "version": {
                                                    "type": "integer"
                                                },
                                                "reports_url_keys_enabled": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/ResourceNotFound"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            },
            "parameters": [
                {
                    "name": "integration",
                    "in": "path",
                    "description": "zapier, make, n8n, sheets, looker, woocommerce or wordpress.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "enum": [
                            "zapier",
                            "make",
                            "n8n",
                            "sheets",
                            "looker",
                            "woocommerce",
                            "reporting",
                            "wordpress"
                        ]
                    }
                }
            ]
        },
        "/v1/integrations/keys": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List integration keys",
                "description": "The caller's integration keys grouped by integration (never the secret), each with label (\"Make (created by Claude, Nov 8)\"), scopes, businesses, created_via, created_by_client and last_used_at, plus the webhooks the integration subscribed (made with one of its keys, or by target host: hooks.zapier.com, *.make.com, *.n8n.cloud) with the last delivery. Revoked publishable keys only with `include_revoked=1`. A token limited to some businesses sees only keys inside them. Not for API keys (403 `api_key_not_allowed`).",
                "operationId": "listIntegrationKeys",
                "parameters": [
                    {
                        "name": "include_revoked",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1IntegrationKeyGroup"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "403": {
                        "description": "api_key_not_allowed"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create integration key",
                "description": "Creates the key an integration needs, from its preset: a secret key (`gk_live_...`) with the preset's scopes for Zapier, Make, n8n, Sheets and Looker, a publishable key (`gk_pub_...`) for exactly one business for WordPress, or a `custom` secret key with the `scopes` given. A key made with an OAuth token gets only scopes the token has (403 `insufficient_scope`); `companies` \"all\" (default; for a token limited to some businesses: exactly those) or company uuids the caller can use (404 otherwise; the key is limited to them). The secret is in `data.key` in this response only; every call makes a new key (`meta.note`). Records `created_via` and the AI app's name (`created_by_client`). Audited; 10 an hour per user (429 `rate_limited`). Not for API keys (403 `api_key_not_allowed`).",
                "operationId": "createIntegrationKey",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "integration"
                                ],
                                "properties": {
                                    "integration": {
                                        "type": "string",
                                        "example": "make",
                                        "enum": [
                                            "zapier",
                                            "make",
                                            "n8n",
                                            "sheets",
                                            "looker",
                                            "woocommerce",
                                            "reporting",
                                            "wordpress",
                                            "custom"
                                        ]
                                    },
                                    "name": {
                                        "type": "string",
                                        "example": "Make",
                                        "maxLength": 100
                                    },
                                    "companies": {
                                        "description": "\"all\", or a list of company uuids (WordPress: exactly one).",
                                        "oneOf": [
                                            {
                                                "type": "string",
                                                "enum": [
                                                    "all"
                                                ]
                                            },
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                }
                                            }
                                        ]
                                    },
                                    "scopes": {
                                        "description": "custom only: the scopes of the key.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "reviews:read",
                                                "reviews:write",
                                                "companies:read",
                                                "companies:write",
                                                "directory:read"
                                            ]
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created (the secret in data.key, once)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "allOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1IntegrationKey"
                                                },
                                                {
                                                    "required": [
                                                        "key",
                                                        "next_steps",
                                                        "setup"
                                                    ],
                                                    "properties": {
                                                        "key": {
                                                            "description": "The secret (`gk_live_...` or `gk_pub_...`), shown only here.",
                                                            "type": "string"
                                                        },
                                                        "next_steps": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        },
                                                        "setup": {
                                                            "oneOf": [
                                                                {
                                                                    "$ref": "#/components/schemas/V1IntegrationSetup"
                                                                },
                                                                {
                                                                    "type": "object",
                                                                    "nullable": true,
                                                                    "enum": [
                                                                        null
                                                                    ]
                                                                }
                                                            ],
                                                            "description": "Null for `custom`."
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            ]
                                        },
                                        "meta": {
                                            "required": [
                                                "note",
                                                "shown_once",
                                                "earlier_active"
                                            ],
                                            "properties": {
                                                "note": {
                                                    "type": "string"
                                                },
                                                "shown_once": {
                                                    "type": "boolean"
                                                },
                                                "earlier_active": {
                                                    "description": "Earlier keys of this integration still active.",
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "description": "api_key_not_allowed, insufficient_scope, role_forbidden"
                    },
                    "404": {
                        "description": "company_not_found"
                    },
                    "429": {
                        "description": "rate_limited"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            }
        },
        "/v1/integrations/keys/{type}/{id}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Revoke integration key",
                "description": "Revokes one of the caller's integration keys: a secret key is deleted (its webhooks stop), a publishable key gets `revoked_at` (kept, never deleted; owners and admins of its business, `reviews:write` for a token). Audited. Not for API keys.",
                "operationId": "revokeIntegrationKey",
                "responses": {
                    "204": {
                        "description": "Revoked"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/ResourceNotFound"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            },
            "parameters": [
                {
                    "name": "type",
                    "in": "path",
                    "description": "secret or publishable (the `type` of the key in the list).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "enum": [
                            "secret",
                            "publishable"
                        ]
                    }
                },
                {
                    "name": "id",
                    "in": "path",
                    "description": "Key id.",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/companies/{company}/locations": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List an HQ's locations",
                "description": "Scope: `companies:read`. The HQ (first) and its locations by name, for location pickers and the `location` filter of the other HQ views. 403 `location_group_access_required` when the caller sees this company but not all of its locations; 409 `not_an_hq` for a location of another HQ.",
                "operationId": "v1ListLocations",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1LocationListItem"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count",
                                                "hq"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "hq": {
                                                    "$ref": "#/components/schemas/V1LocationHq"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/admin/browser-accounts": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List the Grades-owned reporter accounts",
                "description": "Scope: `companies:read`, platform super admins only. The Grades-owned reporter accounts (every status) with `usage{site_actions_24h, daily_limit}`. `meta`: as the company list (`enabled`, `worker_available`, `connect`, `consent_version`), `sites`: the platform report sites with the texts to acknowledge per sign-in method, `policy_note` and `recommended_method` (`live`), `daily_limit`, and `report_jobs`: the latest 25 browser report jobs of every account (`status`, `status_text`, `rehearsal`, `stopped_before`, `evidence_url`; status `rehearsed` = stopped before the final submit, nothing filed).",
                "operationId": "v1ListPlatformBrowserAccounts",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1PlatformBrowserAccount"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1PlatformBrowserAccountListMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Connect a Grades-owned reporter account",
                "description": "Scope: `companies:write`, platform super admins only. Records the acknowledgment (`consent: true` with the current `consent_version`) and opens a connect attempt for grades.com's own account on `site` (a platform report site), exactly like a company connect: `live` (recommended: Google often blocks automated sign-in) returns `meta.connect_url`, `credentials` returns `meta.connect_token` + `meta.ws_url`. 503 `browser_automation_disabled`, `browser_worker_unavailable`, `credentials_unavailable`; 429 after 10 starts per user per hour.",
                "operationId": "v1ConnectPlatformBrowserAccount",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "site",
                                    "consent",
                                    "consent_version"
                                ],
                                "properties": {
                                    "site": {
                                        "type": "string",
                                        "example": "google"
                                    },
                                    "method": {
                                        "type": "string",
                                        "default": "live",
                                        "enum": [
                                            "live",
                                            "credentials"
                                        ]
                                    },
                                    "consent": {
                                        "type": "boolean",
                                        "example": true
                                    },
                                    "consent_version": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created (same shape as the company connect)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserSession"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1BrowserConnectStartMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/admin/browser-accounts/{session}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Disconnect a Grades-owned reporter account",
                "description": "Scope: `companies:write`, platform super admins only. Disconnects grades.com's own account: the stored session is deleted at once, an open connect attempt and the queued jobs are canceled (their agent actions fail and can be approved again; new reports then use a company's own account where there is one). Works while the feature is off.",
                "operationId": "v1RevokePlatformBrowserAccount",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/admin/browser-accounts/{session}/connect/{attempt}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a reporter account connect attempt",
                "description": "Scope: `companies:read`, platform super admins only. The attempt's status, for polling.",
                "operationId": "v1GetPlatformBrowserConnectAttempt",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserConnectAttempt"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Cancel a reporter account connect attempt",
                "description": "Scope: `companies:write`, platform super admins only. Cancels an open attempt. Idempotent.",
                "operationId": "v1CancelPlatformBrowserConnectAttempt",
                "responses": {
                    "204": {
                        "description": "Canceled"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "name": "session",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                },
                {
                    "name": "attempt",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/radar/settings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review radar settings",
                "description": "Scope: `companies:read`. `enabled`: the weekly scan and AI probe run (default off); the last runs.",
                "operationId": "v1GetRadarSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RadarSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update review radar settings",
                "description": "Scope: `reviews:write`. `{\"enabled\": true}` turns the weekly radar on.",
                "operationId": "v1UpdateRadarSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "enabled"
                                ],
                                "properties": {
                                    "enabled": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RadarSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/radar/scan": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Run a review radar scan",
                "description": "Scope: `reviews:write`. Searches Google now for `\"<name>\" reviews` (a location under an HQ: `\"<name>\" <city>`), `\"<name>\" <city> reviews` and `\"<name>\" complaints` (2 pages, US, AI Overview) through Apify and stores the results as mentions, scored for relevance (low ones stored dismissed). Takes up to about two minutes; costs up to `RADAR_MAX_COST_USD`. 429 (with `Retry-After`) when the company was scanned in the last 6 hours; 503 `radar_unavailable` without an Apify token.",
                "operationId": "v1RunRadarScan",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RadarScanResult"
                                        },
                                        "meta": {
                                            "required": [
                                                "new_mentions"
                                            ],
                                            "properties": {
                                                "new_mentions": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/radar/mentions": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review radar mentions",
                "description": "Scope: `reviews:read`. Mentions, newest first. Filters: `status` (`new`, `seen`, `dismissed`; default: all but dismissed), `since` (first seen on or after, date or date-time), `engine` (comma-separated), `tracked` (`true` / `false`: the review site is / is not a connected source), `review_pages` (`true`: review pages only), `min_relevance` (0-1: relevance at least this), `limit` (1-100, default 50), `cursor`. Mentions the radar scored below `RADAR_MIN_RELEVANCE` (0.35) are stored `dismissed` with `dismiss_reason: low_relevance`, search-result and category pages with `search_page` (`?status=dismissed` lists them).",
                "operationId": "v1ListRadarMentions",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewMention"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/radar/mentions/{mention}": {
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review radar mention",
                "description": "Scope: `reviews:write`. `{\"status\": \"dismissed\"}` hides a mention (also `seen`, `new`); a status set by a user is kept by later scans and `radar:reclassify`.",
                "operationId": "v1UpdateRadarMention",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "status"
                                ],
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "new",
                                            "seen",
                                            "dismissed"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewMention"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "mention",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/companies/{company}/radar/ai-probe": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Run an AI Reputation probe",
                "description": "Scope: `reviews:write`. Asks each configured AI engine (`gemini`, `openai`, `perplexity`, `anthropic`; each needs its API key on the server) three questions about the company's reviews, with web search, and extracts sentiment, summary, rating claims, complaints and cited URLs. Optional `{\"engines\": [...]}`. Each answer is judged for whether it is about the business (`mentioned`) and its quoted ratings are checked against the stored data (`rating_quotes`, no extra paid call); `data.measures` sums the run up. Takes up to about 90 seconds; costs up to `AI_PROBE_MAX_COST_USD`. 429 within 24 hours of the last probe; 503 `ai_probe_unavailable` when no engine has a key (`meta.engines_skipped`).",
                "operationId": "v1RunAiProbe",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "engines": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "gemini",
                                                "openai",
                                                "perplexity",
                                                "anthropic"
                                            ]
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AiProbeRunResult"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1AiProbeRunMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/radar/ai-perception": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "AI Reputation",
                "description": "Scope: `reviews:read`. What AI assistants say about the company: `summary` (latest probe per engine: sentiment, score, summary, rating claims, complaints, cited domains, whether it mentioned the business and its checked rating quotes), `measures` (the four AI Reputation measures of those latest probes: Mentioned, Sentiment, Rating accuracy, Review sites cited), `probes` (the answers of those latest probes) and `history` (sentiment, mentioned and rating accuracy per engine and run, newest first). Filters: `engine`, `since` (history from this date). `meta.cadence`: how often the plan checks (days, label daily / weekly / monthly) and the next scheduled check. Without a plan (a claimed listing): 402 `plan_upgrade_required` with a `teaser` (mentioned N of M assistants, overall sentiment, last check).",
                "operationId": "v1GetAiPerception",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AiPerception"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1AiPerceptionMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/recovery/cases": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List recovery cases",
                "description": "Scope: `reviews:read`. Recovery cases, newest first. `status`: `open` (new and contacted, the default), `all`, or one or more of `new,contacted,resolved,closed`. `location`: an HQ's locations (`all` or uuids, comma-separated; callers who see every location). `assignee=me` keeps the caller's cases. Cursor pagination (`meta.next_cursor`). `meta.counts` holds the counts per status in the same scope.",
                "operationId": "v1RecoveryCases",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "location",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "assignee",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "me"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 200,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "description": "Cases without `events`.",
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1RecoveryCase"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "counts": {
                                                    "description": "Cases per status in the same scope.",
                                                    "properties": {
                                                        "new": {
                                                            "type": "integer"
                                                        },
                                                        "contacted": {
                                                            "type": "integer"
                                                        },
                                                        "resolved": {
                                                            "type": "integer"
                                                        },
                                                        "closed": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "open": {
                                                    "description": "New plus contacted.",
                                                    "type": "integer"
                                                },
                                                "locations": {
                                                    "description": "How many locations the list covers.",
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/recovery/cases/{case}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a recovery case",
                "description": "Scope: `reviews:read`. One recovery case with its history (`events`, oldest first).",
                "operationId": "v1RecoveryCase",
                "parameters": [
                    {
                        "name": "case",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RecoveryCase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a recovery case",
                "description": "Scope: `reviews:write`. Owners, admins and approvers. `status` (new, contacted, resolved, closed; resolved sets the outcome `resolved`, closing needs an `outcome`: no_response, declined, not_applicable or resolved), `assignee` (a user uuid of the location who can approve, or null), `contact` (a review-request contact uuid, or null). Every change is kept in the case history.",
                "operationId": "v1UpdateRecoveryCase",
                "parameters": [
                    {
                        "name": "case",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "new",
                                            "contacted",
                                            "resolved",
                                            "closed"
                                        ]
                                    },
                                    "outcome": {
                                        "type": "string",
                                        "enum": [
                                            "resolved",
                                            "no_response",
                                            "declined",
                                            "not_applicable"
                                        ]
                                    },
                                    "assignee": {
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    },
                                    "contact": {
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RecoveryCase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/recovery/cases/{case}/notes": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Add a note to a recovery case",
                "description": "Scope: `reviews:write`. Adds an internal note (at most 2,000 characters) to the case history.",
                "operationId": "v1RecoveryCaseNote",
                "parameters": [
                    {
                        "name": "case",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "maxLength": 2000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RecoveryCase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/recovery/cases/{case}/outreach": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Message the customer of a recovery case",
                "description": "Scope: `reviews:write`. Sends a service-recovery message to the case's contact: `channel` email or sms, a `template` (apology, follow_up, resolved) or your own `text` (and `subject` for e-mail; merge fields {{first_name}}, {{last_name}}, {{name}}, {{business_name}}). From the business, like review requests: the contact's opt-outs and suppressions, SMS consent, quiet hours in the customer's time zone, the daily caps and one message per address per day apply (409 `channel_unavailable`, `quiet_hours`, `recently_messaged`, 429 `daily_cap`, 409 `sending_disabled` while sending is switched off). A recovery message never links to a review site or asks about the review (400). An unknown `template` is 400 `body.template`. The first message marks a new case `contacted`.",
                "operationId": "v1RecoveryCaseOutreach",
                "parameters": [
                    {
                        "name": "case",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "channel"
                                ],
                                "properties": {
                                    "channel": {
                                        "type": "string",
                                        "enum": [
                                            "email",
                                            "sms"
                                        ]
                                    },
                                    "template": {
                                        "type": "string",
                                        "enum": [
                                            "apology",
                                            "follow_up",
                                            "resolved"
                                        ]
                                    },
                                    "text": {
                                        "type": "string"
                                    },
                                    "subject": {
                                        "type": "string",
                                        "maxLength": 200
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RecoveryCase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/recovery/cases/{case}/ask-update": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Invite the customer to update their review",
                "description": "Scope: `reviews:write`. On any case, whatever its status, sends ONE message that the review can be edited: the fixed text \"Thank you for telling us about your visit. Your review is yours: you are free to edit it at any time, or to leave it as it is.\" (the same for everyone) with the link to where the customer can edit it (Google: the place's reviews page). `extra`: one optional sentence of your own, at most 200 characters (no links, offers or conditions; 400 `body.extra`). 409 `already_asked`, `no_review` (private feedback), `site_forbids_requests` (Yelp, employer sites), `no_review_link`, plus the sending refusals of outreach.",
                "operationId": "v1RecoveryCaseAskUpdate",
                "parameters": [
                    {
                        "name": "case",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "channel": {
                                        "type": "string",
                                        "enum": [
                                            "email",
                                            "sms"
                                        ]
                                    },
                                    "extra": {
                                        "type": "string",
                                        "maxLength": 200
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RecoveryCase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/recovery/stats": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Recovery stats",
                "description": "Scope: `reviews:read`. Recovery figures for `from`..`to` (dates in the company's time zone; default the last 30 days): open cases now, cases opened and contacted, median hours to the first contact, the share of decided cases resolved, outcomes, and reviews updated after resolution. `location` as in the case list.",
                "operationId": "v1RecoveryStats",
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "location",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "open": {
                                                    "description": "Open cases now.",
                                                    "type": "integer"
                                                },
                                                "open_without_contact": {
                                                    "type": "integer"
                                                },
                                                "opened": {
                                                    "type": "integer"
                                                },
                                                "opened_by_source": {
                                                    "properties": {
                                                        "review": {
                                                            "type": "integer"
                                                        },
                                                        "feedback": {
                                                            "type": "integer"
                                                        },
                                                        "escalation": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "contacted": {
                                                    "type": "integer"
                                                },
                                                "median_hours_to_first_contact": {
                                                    "type": "number",
                                                    "nullable": true
                                                },
                                                "decided": {
                                                    "type": "integer"
                                                },
                                                "resolved": {
                                                    "type": "integer"
                                                },
                                                "resolved_share": {
                                                    "description": "Resolved / decided (0-1), null when none decided.",
                                                    "type": "number",
                                                    "nullable": true
                                                },
                                                "outcomes": {
                                                    "description": "Case count per outcome (only outcomes that occur).",
                                                    "type": "object",
                                                    "additionalProperties": {
                                                        "type": "integer"
                                                    }
                                                },
                                                "updated_after_resolution": {
                                                    "type": "integer"
                                                },
                                                "improved_after_resolution": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "from": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "to": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "timezone": {
                                                    "type": "string"
                                                },
                                                "locations": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/recovery/settings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Recovery settings",
                "description": "Scope: `reviews:read`. Whether recovery cases open for this business (`enabled`, on by default), the thresholds, the outreach templates and the update invitation's fixed text.",
                "operationId": "v1RecoverySettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RecoverySettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update recovery settings",
                "description": "Scope: `reviews:write`. Owners and admins. `enabled` false stops new cases; open cases stay.",
                "operationId": "v1UpdateRecoverySettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "enabled"
                                ],
                                "properties": {
                                    "enabled": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1RecoverySettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/reviews": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List reviews",
                "description": "Scope: `reviews:read`. Same filters as the dashboard list; cursor pagination (follow `meta.next_cursor` until it is null). Reviews removed from the review site are excluded unless `include_removed=1` (or `include_deleted=true`); they carry `removed_at` and `removal_reason`.",
                "operationId": "v1ListReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/V1Limit"
                    },
                    {
                        "$ref": "#/components/parameters/V1Cursor"
                    },
                    {
                        "$ref": "#/components/parameters/V1ReviewSort"
                    },
                    {
                        "$ref": "#/components/parameters/StartDate"
                    },
                    {
                        "$ref": "#/components/parameters/EndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewSourceDrivers"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMinRating"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMaxRating"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewHasCompanyResponse"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMinLength"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewMaxLength"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewHideInWidget"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewS"
                    },
                    {
                        "$ref": "#/components/parameters/V1IncludeRemoved"
                    },
                    {
                        "$ref": "#/components/parameters/V1IncludeDeleted"
                    },
                    {
                        "$ref": "#/components/parameters/IncludeTotalQuantity"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Review"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "sort": {
                                                    "type": "string"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                },
                                                "total": {
                                                    "description": "Only with `include_total_quantity=true`.",
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create a review",
                "description": "Scope: `reviews:write` (owners, admins and members). Adds one review the business holds elsewhere (its shop, its CRM, a review site). Say where it is FROM with `site` (a review site Grades.com knows), `source_url` (the site is derived from its host) or `source_label` (your own system, e.g. \"WooCommerce store\"); without them the source is \"not given\". `arrival` is always `api`: Grades.com did not collect or verify it, it counts in your own figures and never on the public directory. A Yelp origin falls under the Yelp text rule. Idempotent: the same `external_id` (per origin) returns the stored review with 200 and changes nothing; an `Idempotency-Key` header returns the review its first request created (409 `idempotency_key_reused` for another body). Raises `review.created` (not to the webhooks the same key or OAuth grant registered), the new-review notices and the review agent. No rating filter exists: every rating is stored the same way.",
                "operationId": "v1CreateReview",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "description": "Optional, 1 to 255 visible characters (a UUID). A retry with the same key and body returns the first review.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "rating": {
                                        "type": "integer",
                                        "nullable": true,
                                        "maximum": 5,
                                        "minimum": 1
                                    },
                                    "text": {
                                        "description": "Up to 10,000 characters. A rating, a text or both.",
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "reviewer_name": {
                                        "description": "The name to show (`author` is accepted too).",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 120
                                    },
                                    "published_at": {
                                        "description": "When the review was written; not in the future. Default: now.",
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "external_id": {
                                        "description": "Your id of the review: unique per business and origin, makes retries safe.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 191
                                    },
                                    "location": {
                                        "description": "Where the reviewer or the store is, as text (\"Austin, TX\").",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 120
                                    },
                                    "site": {
                                        "description": "A review site slug Grades.com knows (`google`, `yelp`, `facebook`, ...).",
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "source_url": {
                                        "description": "The review's URL (http or https).",
                                        "type": "string",
                                        "format": "url",
                                        "nullable": true
                                    },
                                    "source_label": {
                                        "description": "Your own system: \"WooCommerce store\", \"CRM\".",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 60
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Review"
                                        },
                                        "meta": {
                                            "properties": {
                                                "created": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Already stored by an earlier request (same `external_id` or `Idempotency-Key`): nothing changed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Review"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "yelp_consent",
                    "in": "query",
                    "description": "true = include the text of Yelp reviews (internal use only) when the company has recorded the Yelp consent (Review Showcase notice); otherwise they come back with `text_policy: aggregate`. Never for Ask Grades.",
                    "required": false,
                    "schema": {
                        "type": "boolean"
                    }
                }
            ]
        },
        "/v1/companies/{company}/reviews/{review}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get review",
                "description": "Scope: `reviews:read`. Also returns reviews removed from the review site.",
                "operationId": "v1GetReview",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Review"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Hide or show a review",
                "description": "Scope: `reviews:write`. `hidden: true` hides the review from public displays (the public reviews API); `false` shows it again. The review stays on its site.",
                "operationId": "v1UpdateReview",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "hidden"
                                ],
                                "properties": {
                                    "hidden": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Review"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                },
                {
                    "name": "yelp_consent",
                    "in": "query",
                    "description": "true = include the text of Yelp reviews (internal use only) when the company has recorded the Yelp consent (Review Showcase notice); otherwise they come back with `text_policy: aggregate`. Never for Ask Grades.",
                    "required": false,
                    "schema": {
                        "type": "boolean"
                    }
                }
            ]
        },
        "/v1/companies/{company}/reviews/{review}/history": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review history (archive)",
                "description": "Scope: `reviews:read`. The review archive: the versions Grades kept before each change, oldest first. `edited` = the review before the reviewer edited it, `removed_from_source` = as it was when its site removed it, `restored` = before it came back. The current version is the review itself (`GET .../reviews/{review}`). Works for removed reviews too.",
                "operationId": "v1GetReviewHistory",
                "responses": {
                    "200": {
                        "description": "OK: the same payload as the dashboard twin (one schema for both).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewHistory"
                                        },
                                        "meta": {
                                            "properties": {
                                                "yelp_text": {
                                                    "$ref": "#/components/schemas/V1YelpTextMeta"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                },
                {
                    "name": "yelp_consent",
                    "in": "query",
                    "description": "true = include the text of Yelp reviews (internal use only) when the company has recorded the Yelp consent (Review Showcase notice); otherwise they come back with `text_policy: aggregate`. Never for Ask Grades.",
                    "required": false,
                    "schema": {
                        "type": "boolean"
                    }
                }
            ]
        },
        "/v1/companies/{company}/reviews/{review}/flag": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Flag a review",
                "description": "Scope: `reviews:write`. Records that the review breaks the review site's policy. Nothing is sent to the site: follow `next_steps` to report it there, then PATCH the flag.",
                "operationId": "v1FlagReview",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "reason"
                                ],
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "enum": [
                                            "not_a_customer",
                                            "competitor",
                                            "spam",
                                            "off_topic",
                                            "harassment",
                                            "pii",
                                            "conflict_of_interest",
                                            "duplicate",
                                            "fake",
                                            "policy_other"
                                        ]
                                    },
                                    "details": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 5000
                                    },
                                    "evidence_urls": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "url"
                                        },
                                        "nullable": true,
                                        "maxItems": 20
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewFlag"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/v1/companies/{company}/flags": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review flags",
                "description": "Scope: `reviews:read`. The company's review flags, newest first. Cursor pagination: pass `meta.next_cursor` back as `cursor`.",
                "operationId": "v1ListFlags",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "description": "Only flags in this status.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "open",
                                "submitted",
                                "resolved",
                                "rejected",
                                "withdrawn"
                            ]
                        }
                    },
                    {
                        "name": "review",
                        "in": "query",
                        "description": "Only flags of this review (uuid).",
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 50,
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewFlag"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/flags/{flag}": {
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review flag",
                "description": "Scope: `reviews:write`. Records the progress of the manual report: `submitted` sets `submitted_at`; `resolved`, `rejected` and `withdrawn` set `resolved_at`. Send at least one field. An unknown `status` answers 422 with the `allowed` values.",
                "operationId": "v1UpdateFlag",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "open",
                                            "submitted",
                                            "resolved",
                                            "rejected",
                                            "withdrawn"
                                        ]
                                    },
                                    "external_reference": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 255
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 5000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewFlag"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "flag",
                    "in": "path",
                    "description": "Flag id or uuid.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review pages",
                "description": "Scope: `companies:read`. Every review page of the company, the default first, then oldest first. A company without a page gets its default page here (disabled, links pre-filled from its sources).",
                "operationId": "v1ListReviewPages",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewPage"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create a review page",
                "description": "Scope: `companies:write`, company admins. Creates a page (enabled unless `enabled: false`). `links` omitted: every source of the company, like the default page (`[]`: none). `copy_from` (page id or slug): duplicates that page (explicit fields win). `make_default: true` makes it the default (the previous default keeps its settings and moves to /r/<company>/<its slug>). At most 20 pages.",
                "operationId": "v1CreateReviewPage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "type": "object",
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ReviewPageSettings"
                                    },
                                    {
                                        "properties": {
                                            "make_default": {
                                                "type": "boolean"
                                            },
                                            "copy_from": {
                                                "description": "Page id or slug to duplicate.",
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 64
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "OK: `data` is a V1ReviewPage.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a review page",
                "description": "Scope: `companies:read`. One page with its resolved links, public `url`, `qr_url` and the `available_sources` the company could add.",
                "operationId": "v1GetReviewPage",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review page",
                "description": "Scope: `companies:write`, company admins. Changes the given settings only (PATCH works the same). `links` replaces the whole list; entries carrying the `id` of a link keep it.",
                "operationId": "v1UpdateReviewPage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewPageSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: `data` is a V1ReviewPage.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Delete a review page",
                "description": "Scope: `companies:write`, company admins. Deletes a page and its feedback. The default page cannot be deleted (409 `default_page`): make another page the default first.",
                "operationId": "v1DeleteReviewPage",
                "responses": {
                    "204": {
                        "description": "Deleted"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review page",
                "description": "Same as PUT.",
                "operationId": "v1PatchReviewPage",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewPageSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: `data` is a V1ReviewPage.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/default": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Make a review page the default",
                "description": "Scope: `companies:write`, company admins. Makes the page the company's default (served at /r/<company-slug>); the previous default keeps its settings and is served at /r/<company>/<its slug>.",
                "operationId": "v1MakeDefaultReviewPage",
                "responses": {
                    "200": {
                        "description": "OK: `data` is a V1ReviewPage.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/links": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Add a review page link",
                "description": "Scope: `companies:write`, company admins. Adds one link at `position` (0-based; default: last). 409 `link_exists` when the source is already on the page. `meta.link_id` is the new id.",
                "operationId": "v1AddReviewPageLink",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ReviewPageLinkInput"
                                    },
                                    {
                                        "properties": {
                                            "position": {
                                                "type": "integer",
                                                "nullable": true,
                                                "minimum": 0
                                            }
                                        },
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "OK: `data` is a V1ReviewPage.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "required": [
                                                "link_id"
                                            ],
                                            "properties": {
                                                "link_id": {
                                                    "description": "Id of the new link.",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/links/reorder": {
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Reorder review page links",
                "description": "Scope: `companies:write`, company admins. `{\"ids\": [...]}` names every link of the page exactly once, in the new order.",
                "operationId": "v1ReorderReviewPageLinks",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "ids"
                                ],
                                "properties": {
                                    "ids": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 64
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: `data` is a V1ReviewPage.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/links/{link}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Remove a review page link",
                "description": "Scope: `companies:write`, company admins. Removes the link with that id.",
                "operationId": "v1RemoveReviewPageLink",
                "responses": {
                    "200": {
                        "description": "OK: `data` is a V1ReviewPage.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPage"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                },
                {
                    "name": "link",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/suggestions": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Suggested order of a review page",
                "description": "Scope: `companies:read`. Where one more positive review matters most for this business: every review site of the company (connected sources and profiles its directory listings know) with a weight of 0-100 (AI citations 35, search results 15, site popularity 15, impact of one more review 35; Yelp and employer-review sites 0, never suggested), the human reasons, and the page link of each site. Stored data only (no paid call); recomputed daily, `refresh=1` recomputes now. `order` / `also` are the page link ids in suggested order.",
                "operationId": "v1GetReviewPageSuggestions",
                "parameters": [
                    {
                        "name": "refresh",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPageSuggestions"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/preview": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Preview a review page",
                "description": "Scope: `companies:read`. The public page as it would look with the given settings (same body as PATCH, nothing is saved): `html` (the page itself, with a `<base>` to this host and inert buttons, to show in a sandboxed iframe) and `appearance` (the effective colors, as in V1ReviewPage). Invalid settings answer 400 like PATCH, including the text rules (no review incentives, no review gating).",
                "operationId": "v1PreviewReviewPage",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewPageSettings"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPagePreview"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/activity": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get review page activity",
                "description": "Scope: `companies:read`. What visitors of the page did over a period (docs/review-pages.md \"Activity\"): visits (one per visitor and day; crawlers, prefetches and owner previews not counted), how many clicked a review site or \"Leave a review on Grades.com\" and the rate, clicks per button, split by source (`link`, `qr` printed QR code, `counter` counter screen, `app-qr`, `app-tap`, `request` review request) in a fixed order and by label (the device or place from `?label=`, e.g. \"Front desk\"; null = no label) alphabetically, never ranked. `reviews`: the business's new reviews in the same period; they can not be tied to visits. Period: `from` and `to` (YYYY-MM-DD, UTC days, at most 366 days), or `days` (1-366, default 30, ending today).",
                "operationId": "v1GetReviewPageActivity",
                "parameters": [
                    {
                        "name": "days",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 366,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPageActivity"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-pages/{page}/feedback": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review page feedback",
                "description": "Scope: `companies:read`. Private feedback sent through the page's form, newest first. `limit` (1-100, default 25), `cursor` (`meta.next_cursor`).",
                "operationId": "v1ListReviewPageFeedback",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewPageFeedback"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "page",
                    "in": "path",
                    "description": "Page id (uuid), slug or `default`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-posts": {
            "get": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "List sets of posts",
                "description": "Scope: `reviews:read`. The business's sets of posts, newest first (keyset `cursor`, 25 a page). Sets are kept: history is never deleted.",
                "operationId": "v1ListReviewPosts",
                "parameters": [
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewPostSet"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "Create a set of posts",
                "description": "Scope: `reviews:write` (audited). Queues a set of posts (12 banners, the vertical video, its poster and a caption) made from one review; 202 with the set (`status` queued), ready within minutes. One set at a time per business: 409 `review_post_set_in_progress`; 429 `review_posts_daily_cap` past the daily safety cap; 402 `billing_locked` for a locked location; 422 quote refusals as for the preview.",
                "operationId": "v1CreateReviewPosts",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewPostInput"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Queued",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPostSet"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-posts/status": {
            "get": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "Social Posts status",
                "description": "Scope: `reviews:read`. Whether Social Posts from a review is on for the business (404 when it is not), the set being made (`active_set`, null when none), sets made today and the daily cap, and whether the business is healthcare (the picker then offers only reviews without clinical content).",
                "operationId": "v1ReviewPostsStatus",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "enabled": {
                                                    "type": "boolean"
                                                },
                                                "active_set": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/V1ReviewPostSet"
                                                        },
                                                        {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "enum": [
                                                                null
                                                            ]
                                                        }
                                                    ]
                                                },
                                                "today": {
                                                    "type": "integer"
                                                },
                                                "daily_cap": {
                                                    "type": "integer"
                                                },
                                                "healthcare": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-posts/candidates": {
            "get": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "List reviews for posts",
                "description": "Scope: `reviews:read`. The business's reviews with text that a set of posts can be made from, newest first (keyset `cursor`, 25 a page). Never Yelp reviews, removed reviews or Grades.com reviews that are not public. Each says whether it is `eligible` (else `ineligible_reason`: `low_rating`, `clinical`, `too_short`, `too_long`, `unknown_source`, ...), its `units` (the clauses a trim keeps or drops), the default trims and whether it is `suggested` (five stars, 40-220 characters). `site` filters by platform or driver.",
                "operationId": "v1ReviewPostCandidates",
                "parameters": [
                    {
                        "name": "stars",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 5,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "site",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        },
                        "example": "google"
                    },
                    {
                        "name": "suggested",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewPostCandidate"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-posts/preview": {
            "post": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "Preview a set of posts",
                "description": "Scope: `reviews:read`. The HTML of every size and of the video for a body, exactly as the render will draw them (fonts and logos inlined, no network; the video loops on its own clock). Makes no files, no set. Same refusals as create (422 `quote_cut_changes_meaning`, `quote_too_long`, `quote_too_short`, `review_not_eligible`).",
                "operationId": "v1PreviewReviewPosts",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ReviewPostInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPostPreview"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-posts/{set}": {
            "get": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "Show a set of posts",
                "description": "Scope: `reviews:read`. One set of posts (poll it until `status` is ready or failed).",
                "operationId": "v1ShowReviewPosts",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewPostSet"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "set",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-posts/{set}/download": {
            "get": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "Download a set of posts (ZIP)",
                "description": "Scope: `reviews:read`. The ZIP of a ready set: `social/` (1080x1080 and 1200x628 PNGs, the MP4, its poster, caption.txt), `google-ads/` (the 10 display banner PNGs) and README.txt at the root (which folder is which, the review site and date, and that the quote was only cut). 409 `review_post_set_not_ready`.",
                "operationId": "v1DownloadReviewPosts",
                "responses": {
                    "200": {
                        "description": "The ZIP",
                        "content": {
                            "application/zip": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "set",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-posts/{set}/files/{name}": {
            "get": {
                "tags": [
                    "Social Posts"
                ],
                "summary": "Download one file of a set of posts",
                "description": "Scope: `reviews:read`. One file of a ready set by its `name` (from `files`).",
                "operationId": "v1ReviewPostFile",
                "responses": {
                    "200": {
                        "description": "The file (image/png, video/mp4 or text/plain)",
                        "content": {
                            "image/png": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            },
                            "video/mp4": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            },
                            "text/plain": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "set",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                },
                {
                    "name": "name",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string"
                    },
                    "example": "banner-300x250.png"
                }
            ]
        },
        "/v1/companies/{company}/reviews/{review}/reply": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Reply to a review",
                "description": "Scope: `reviews:write`. Stores the reply and, for Google reviews with `publish: true`, posts it to Google (`status: published`). Other sites have no reply API: the reply is stored (`status: saved`) and `manual_url` links the review so the owner can paste it. A failed Google push also answers `saved`, with `push_error`. If the review already has a public reply, send `replace: true` (otherwise 422).",
                "operationId": "v1ReplyToReview",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "maxLength": 4000,
                                        "minLength": 1
                                    },
                                    "publish": {
                                        "description": "Post to the review site when it has a reply API.",
                                        "type": "boolean",
                                        "default": true
                                    },
                                    "replace": {
                                        "description": "Overwrite an existing public reply.",
                                        "type": "boolean",
                                        "default": false
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Reply"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Delete a reply",
                "description": "Scope: `reviews:write`. Deletes the reply stored in Grades and, if it was published to Google through Grades, deletes it on Google too (502 if Google refuses; the reply is still removed from Grades). Replies posted directly on a review site are not touched; 404 when the review has no reply in Grades.",
                "operationId": "v1DeleteReviewReply",
                "responses": {
                    "204": {
                        "description": "Deleted"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/v1/companies/{company}/reviews/{review}/reply-draft": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Draft a reply with AI",
                "description": "Scope: `reviews:write`. Writes a reply suggestion with AI from the company's AI settings (description, industry, tone, reply mode) and its past replies, under the same reply rules, voice, checks and sign-off line as review-agent drafts (`needs_review` / `failed_rules` say what still breaks a rule after one rewrite). Nothing is stored or posted. Counts toward the company's monthly AI limit (429 when reached). 403 when the company's AI reply mode excludes this review, 422 when its AI settings are incomplete.",
                "operationId": "v1DraftReviewReply",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "tone": {
                                        "description": "Overrides the company's tone for this draft.",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "professional",
                                            "friendly",
                                            "apologetic"
                                        ]
                                    },
                                    "instructions": {
                                        "description": "Extra guidance, e.g. \"mention the new opening hours\".",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 1000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "draft": {
                                                    "type": "string"
                                                },
                                                "model": {
                                                    "type": "string",
                                                    "example": "gemini-2.5-flash"
                                                },
                                                "remaining_this_month": {
                                                    "type": "integer"
                                                },
                                                "needs_review": {
                                                    "description": "True when the draft still breaks one of the reply rules after one rewrite (or the rules check could not run): read and edit it before posting.",
                                                    "type": "boolean"
                                                },
                                                "failed_rules": {
                                                    "description": "The rules it still breaks (staff_name, clinical_details, patient_relationship, review_solicitation, signature, wrong_language, contact_details, breaks_rules, rules_check_unavailable); empty when it passed.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "language": {
                                                    "description": "The draft's language (ISO 639-1; the business's reply language setting decides it), null when unknown.",
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "draft_en": {
                                                    "description": "Machine translation of a non-English draft into English (\"Translated by AI\"); never post it.",
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "draft_translation": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/V1Translation"
                                                        },
                                                        {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "enum": [
                                                                null
                                                            ]
                                                        }
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/campaigns": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review request campaigns",
                "description": "Scope: `reviews:read`, company admins. The campaigns (the default one is created on first use); `include_archived=1` adds archived ones; `meta.merge_fields`.",
                "operationId": "v1ListReviewRequestCampaigns",
                "parameters": [
                    {
                        "name": "include_archived",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewRequestCampaign"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "merge_fields": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create a review request campaign",
                "description": "Scope: `reviews:write`, company admins, plan feature `review_requests`. 201 with the campaign.",
                "operationId": "v1CreateReviewRequestCampaign",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "status": {
                                        "type": "string"
                                    },
                                    "is_default": {
                                        "type": "boolean"
                                    },
                                    "channels": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email",
                                                "sms"
                                            ]
                                        }
                                    },
                                    "review_page_id": {
                                        "type": "string"
                                    },
                                    "from_name": {
                                        "type": "string"
                                    },
                                    "reply_to": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "track_opens": {
                                        "type": "boolean"
                                    },
                                    "email_branding": {
                                        "description": "Show the business logo and brand color in the emails (default true)",
                                        "type": "boolean"
                                    },
                                    "email_accent": {
                                        "description": "The button color `#rrggbb`; null = the review page accent",
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "template": {
                                        "description": "An industry template key (GET .../campaign-templates); fills the steps",
                                        "type": "string"
                                    },
                                    "steps": {
                                        "description": "`delay_hours`, `email_subject`, `email_body`, `button_label` (at most 40 characters, null = \"Leave a review\"; subject, text and button text never offer an incentive or ask only for good reviews). `sms_body` is ignored (listed in `meta.ignored`): every text is the fixed Grades.com template of its step.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestCampaign"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReviewRequestCampaignWriteMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/campaign-templates": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List campaign templates",
                "description": "Scope: `reviews:read`, company admins. Starter templates to pass as `template` on campaign create or edit: tones for any business (`group: tone`: `general`, `short_friendly`, `professional`, `service_followup`) and industries (`group: industry`: `dentist`, `auto`, `home_services`, `med_spa`, `legal`). They differ in the email subject, text and button text (`button_label`, null = \"Leave a review\") only; `sms_body` is the same fixed Grades.com text for every template.",
                "operationId": "v1ListReviewRequestCampaignTemplates",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/campaigns/{campaign}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a review request campaign",
                "description": "Scope: `reviews:read`, company admins. `{campaign}` is a uuid or `default`.",
                "operationId": "v1GetReviewRequestCampaign",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestCampaign"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Archive a review request campaign",
                "description": "Scope: `reviews:write`, company admins. Archives the campaign (kept with its history); 409 `default_campaign` for the default one.",
                "operationId": "v1ArchiveReviewRequestCampaign",
                "responses": {
                    "204": {
                        "description": "Archived"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review request campaign",
                "description": "Scope: `reviews:write`, company admins. PUT and PATCH both change the fields sent.",
                "operationId": "v1UpdateReviewRequestCampaign",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "status": {
                                        "type": "string"
                                    },
                                    "is_default": {
                                        "type": "boolean"
                                    },
                                    "channels": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email",
                                                "sms"
                                            ]
                                        }
                                    },
                                    "review_page_id": {
                                        "type": "string"
                                    },
                                    "from_name": {
                                        "type": "string"
                                    },
                                    "reply_to": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "track_opens": {
                                        "type": "boolean"
                                    },
                                    "email_branding": {
                                        "description": "Show the business logo and brand color in the emails (default true)",
                                        "type": "boolean"
                                    },
                                    "email_accent": {
                                        "description": "The button color `#rrggbb`; null = the review page accent",
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "template": {
                                        "description": "An industry template key (GET .../campaign-templates); fills the steps",
                                        "type": "string"
                                    },
                                    "steps": {
                                        "description": "`delay_hours`, `email_subject`, `email_body`, `button_label` (at most 40 characters, null = \"Leave a review\"; subject, text and button text never offer an incentive or ask only for good reviews). `sms_body` is ignored (listed in `meta.ignored`): every text is the fixed Grades.com template of its step.",
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestCampaign"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReviewRequestCampaignWriteMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestCampaignPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/campaigns/{campaign}/preview": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Preview a campaign message",
                "description": "Scope: `reviews:read`, company admins. The rendered email (subject, html, text) and SMS (body, segments) of step `step` (0-2) for `contact_id` or a sample contact.",
                "operationId": "v1PreviewReviewRequestCampaign",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "contact_id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "step": {
                                        "type": "integer",
                                        "maximum": 2,
                                        "minimum": 0
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "email",
                                                "sms"
                                            ],
                                            "properties": {
                                                "email": {
                                                    "description": "null when the campaign does not use email.",
                                                    "properties": {
                                                        "subject": {
                                                            "type": "string"
                                                        },
                                                        "html": {
                                                            "type": "string"
                                                        },
                                                        "text": {
                                                            "type": "string"
                                                        },
                                                        "from": {
                                                            "description": "`Name <address>`",
                                                            "type": "string"
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "sms": {
                                                    "description": "null when the campaign does not use SMS.",
                                                    "properties": {
                                                        "body": {
                                                            "type": "string"
                                                        },
                                                        "segments": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "step": {
                                                    "type": "integer"
                                                },
                                                "postal_address": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "sample_contact": {
                                                    "description": "true = rendered for the sample contact",
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestCampaignPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/campaigns/{campaign}/test": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Send a test of a campaign step to yourself",
                "description": "Scope: `reviews:write`, company admins, plan feature `review_requests`. \"Send me a test\": step `step` (0-2) of the SAVED campaign, rendered exactly as a real send (From, Reply-To, logo, color, button text, footer) for the sample contact Jane Doe, to the signed-in user's own verified address only, subject prefixed \"[Test]\". 10 an hour per user (429 `test_limit`). Creates no contact, request or message, does not count against the sending allowance, carries no tracked link, open pixel or one-click unsubscribe. 409 `email_not_verified`, `no_email_channel`, `no_postal_address`, `campaign_archived`, `recipient_suppressed`.",
                "operationId": "v1TestReviewRequestCampaign",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "step": {
                                        "type": "integer",
                                        "maximum": 2,
                                        "minimum": 0
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "step",
                                                "sent_to",
                                                "subject"
                                            ],
                                            "properties": {
                                                "step": {
                                                    "type": "integer"
                                                },
                                                "sent_to": {
                                                    "description": "The masked address it went to.",
                                                    "type": "string"
                                                },
                                                "subject": {
                                                    "description": "Prefixed \"[Test]\".",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "message_key": {
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestCampaignPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/contacts/{contact}/opt-in": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Opt a review request contact back in",
                "description": "Scope: `reviews:write`. An admin opts the contact back in on `channel` with a `reason` (kept on the opt-out row with the user, audited). Spam complaints and SMS STOP are final: 409 `opt_out_final` (only the customer can opt back in: texting START, or a re-subscribe link). An unsubscribe by link / one-click can be reversed once per contact: 409 `reversal_used` after that. For `sms` the body also carries the consent record (`sms_consent_text` naming Grades.com and STOP, `sms_consent_source`, optional `sms_consent_at`, `sms_consent_ip`). A STOP texted to the Grades.com number (for any business) is final too.",
                "operationId": "v1ReviewRequestContactOptIn",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "channel",
                                    "reason"
                                ],
                                "properties": {
                                    "channel": {
                                        "type": "string",
                                        "enum": [
                                            "email",
                                            "sms"
                                        ]
                                    },
                                    "reason": {
                                        "type": "string",
                                        "maxLength": 500,
                                        "minLength": 5
                                    },
                                    "sms_consent_text": {
                                        "type": "string",
                                        "maxLength": 1000,
                                        "minLength": 20
                                    },
                                    "sms_consent_source": {
                                        "type": "string",
                                        "maxLength": 255
                                    },
                                    "sms_consent_at": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "sms_consent_ip": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The contact",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestContact"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestContactPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/contacts/{contact}/resubscribe-link": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Send a re-subscribe link",
                "description": "Scope: `reviews:write`. Mails the contact ONE signed re-subscribe link (valid 30 days) at the business's request; only the customer's click on it opts the address back in to this business's email requests (also after a spam complaint, which an admin cannot reverse). One link per contact ever (409 `resubscribe_link_used`); 409 `not_opted_out`, `no_email`, `address_bounced`. Records who asked.",
                "operationId": "v1ReviewRequestContactResubscribeLink",
                "responses": {
                    "202": {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestResubscribeLink"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestContactPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/contacts": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review request contacts",
                "description": "Scope: `reviews:read`, company admins. Search `q` (name, email, phone), `tag`, `status` (`active`, `opted_out`), cursor paged.",
                "operationId": "v1ListReviewRequestContacts",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "active",
                                "opted_out"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "1-100, default 25",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "description": "meta.next_cursor of the previous page",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewRequestContact"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Add or update review request contacts",
                "description": "Scope: `reviews:write`, company admins, plan feature `review_requests`. One contact (deduped by email, phone, external id: 201 created, 200 updated, `meta.created`) or `{\"contacts\": [...]}` (up to 500; `meta.created`, `updated`, `failed`, `errors`). `sms_consent: true` needs `sms_consent_text` and `sms_consent_source`; the wording must name Grades.com (the sender of every text) and STOP, else 400 `body.sms_consent_text` (standard wording: settings `sms_consent_default_text`).",
                "operationId": "v1UpsertReviewRequestContact",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 254
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 32
                                    },
                                    "tags": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "external_id": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "timezone": {
                                        "type": "string"
                                    },
                                    "sms_consent": {
                                        "type": "boolean"
                                    },
                                    "sms_consent_text": {
                                        "type": "string"
                                    },
                                    "sms_consent_source": {
                                        "type": "string"
                                    },
                                    "contacts": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "One contact, created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/V1ReviewRequestContactUpsertOne"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "One contact, updated; or the answer to `contacts` (per item counts and errors in `meta`)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/V1ReviewRequestContactUpsertOne"
                                        },
                                        {
                                            "$ref": "#/components/schemas/V1ReviewRequestContactUpsertMany"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/contacts/import": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Import review request contacts (CSV)",
                "description": "Scope: `reviews:write`, company admins, plan feature `review_requests`. A CSV as `file` (multipart) or `csv` (text), with `tags`, `consent_source`, `sms_consent_text`, `sms_consent_source`. Counts in `meta` (`sms_consent_missing`, `email_warnings`).",
                "operationId": "v1ImportReviewRequestContacts",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "csv": {
                                        "type": "string"
                                    },
                                    "tags": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "consent_source": {
                                        "type": "string",
                                        "maxLength": 60
                                    },
                                    "sms_consent_text": {
                                        "type": "string"
                                    },
                                    "sms_consent_source": {
                                        "type": "string",
                                        "maxLength": 255
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: the counts are in `meta`; `data` is always an empty list",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            },
                                            "maxItems": 0
                                        },
                                        "meta": {
                                            "required": [
                                                "rows",
                                                "created",
                                                "updated",
                                                "failed",
                                                "errors"
                                            ],
                                            "properties": {
                                                "rows": {
                                                    "type": "integer"
                                                },
                                                "created": {
                                                    "type": "integer"
                                                },
                                                "updated": {
                                                    "type": "integer"
                                                },
                                                "failed": {
                                                    "type": "integer"
                                                },
                                                "sms_consent_missing": {
                                                    "type": "integer"
                                                },
                                                "email_warnings": {
                                                    "type": "integer"
                                                },
                                                "errors": {
                                                    "description": "Failed rows: the CSV line and the errors per field.",
                                                    "type": "array",
                                                    "items": {
                                                        "properties": {
                                                            "row": {
                                                                "type": "integer"
                                                            },
                                                            "errors": {
                                                                "type": "object",
                                                                "additionalProperties": true
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/contacts/{contact}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a review request contact",
                "description": "Scope: `reviews:read`, company admins. The contact with opt-out state and its last 10 requests.",
                "operationId": "v1GetReviewRequestContact",
                "responses": {
                    "200": {
                        "description": "OK: the contact with `requests`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestContact"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Delete a review request contact",
                "description": "Scope: `reviews:write`, company admins. Soft delete; the opt-outs of its addresses stay.",
                "operationId": "v1DeleteReviewRequestContact",
                "responses": {
                    "204": {
                        "description": "Deleted"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review request contact",
                "description": "Scope: `reviews:write`, company admins. Changes the fields sent (same rules as create); 409 when the email, phone or external id belongs to another contact.",
                "operationId": "v1UpdateReviewRequestContact",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 120
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 254
                                    },
                                    "phone": {
                                        "type": "string",
                                        "maxLength": 32
                                    },
                                    "tags": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    "external_id": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "timezone": {
                                        "type": "string"
                                    },
                                    "sms_consent": {
                                        "type": "boolean"
                                    },
                                    "sms_consent_text": {
                                        "type": "string"
                                    },
                                    "sms_consent_source": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestContact"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestContactPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/contacts/{contact}/opt-out": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Opt a review request contact out",
                "description": "Scope: `reviews:write`, company admins. Manual opt-out on `channel` (`email`, `sms` or `all`); recorded in the opt-out history, never deleted. No plan gate: it works while the location is locked.",
                "operationId": "v1ReviewRequestContactOptOut",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "channel"
                                ],
                                "properties": {
                                    "channel": {
                                        "type": "string",
                                        "enum": [
                                            "email",
                                            "sms",
                                            "all"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The contact",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestContact"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestContactPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/opt-outs": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review request opt-outs",
                "description": "Scope: `reviews:read`, company admins. The opt-out history of the business (never deleted), newest first; filter `channel`.",
                "operationId": "v1ListReviewRequestOptOuts",
                "parameters": [
                    {
                        "name": "channel",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "email",
                                "sms"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "1-100, default 25",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "description": "meta.next_cursor of the previous page",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewRequestOptOut"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                },
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/settings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get review request settings",
                "description": "Scope: `reviews:read`, company admins. The global switch, SMS availability, plan, daily caps, pause, `min_days_between_requests` (14-90, default 30), postal address, quiet hours and `sms_consent_default_text`, and `default_campaign` (`{id, name, status}` of the default campaign, null before the first request; `paused` = requests wait until it is resumed).",
                "operationId": "v1GetReviewRequestSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update review request settings",
                "description": "Scope: `reviews:write`. Changes the business's review request settings: `daily_email_cap`, `daily_sms_cap`, `paused`, and `min_days_between_requests` (14-90; null = the default 30): a new request to a contact who got one within that many days, or has one in progress, is refused with 409 `recently_requested`. Answers the settings (`min_days_between_requests`, `..._default`, `..._range`, `sms_consent_default_text`, ...). Where sending allowances apply (SENDING_ALLOWANCES_STATUS): `extra_sending` (boolean) and `extra_sending_cap_usd` (whole dollars, required when switching it on) let messages above the monthly allowance go out, billed per started block at month close up to the cap; members who manage billing only (403 otherwise); 409 `extra_sending_unavailable` when nobody can be billed (no subscription).",
                "operationId": "v1UpdateReviewRequestSettings",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "daily_email_cap": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "daily_sms_cap": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "paused": {
                                        "type": "boolean"
                                    },
                                    "min_days_between_requests": {
                                        "type": "integer",
                                        "nullable": true,
                                        "maximum": 90,
                                        "minimum": 14
                                    },
                                    "extra_sending": {
                                        "type": "boolean"
                                    },
                                    "extra_sending_cap_usd": {
                                        "type": "integer"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestSettings"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review requests",
                "description": "Scope: `reviews:read`, company admins. Newest first, cursor paged; filters `status`, `campaign` (uuid or `default`) and `contact` (uuid).",
                "operationId": "v1ListReviewRequests",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "campaign",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "contact",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "1-100, default 25",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "description": "meta.next_cursor of the previous page",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewRequest"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Send a review request",
                "description": "Scope: `reviews:write`, company admins, plan feature `review_requests_manual` (every plan; Starter: email only, 50 a calendar month, then 402 `review_requests_manual`; SMS 402 `review_requests`, Pro). A list stops at the monthly number: the rest is skipped with `plan_limit`. Where sending allowances apply (SENDING_ALLOWANCES_STATUS): with extra sending off, 402 `sending_allowance_used` once this month's emails / texts of the plan are used; a list stops there, the rest is skipped with `sending_allowance_used` and counted in `meta.held_back`. Exactly one of `contact_id`, `contact` (an inline contact, upserted), `contacts` (a list, answered per item in `meta`) or `tag`. Optional `campaign` (uuid or `default`), `external_ref` (idempotent: the same reference answers the existing request with `meta.existing: true`), `send_at` or `delay_minutes`, `channels`. 202 when queued. 409 `opted_out`, `no_channel`, `campaign_archived`, `review_page_disabled`, `recently_requested`, `already_reviewed`. Nothing is sent while `REVIEW_REQUESTS_ENABLED` is off, or while `campaign.status` is `paused` (the request waits until the campaign is resumed).",
                "operationId": "v1SendReviewRequest",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "contact_id": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "contact": {
                                        "type": "object"
                                    },
                                    "contacts": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    },
                                    "tag": {
                                        "type": "string",
                                        "maxLength": 40
                                    },
                                    "campaign": {
                                        "type": "string"
                                    },
                                    "external_ref": {
                                        "type": "string",
                                        "maxLength": 100
                                    },
                                    "send_at": {
                                        "type": "string",
                                        "format": "date-time"
                                    },
                                    "delay_minutes": {
                                        "type": "integer",
                                        "maximum": 43200,
                                        "minimum": 0
                                    },
                                    "channels": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "email",
                                                "sms"
                                            ]
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Queued: one request (`contact_id` / `contact`) or the requests of a list or tag (`contacts` / `tag`, counts and skipped items in `meta`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/V1ReviewRequestSendOne"
                                        },
                                        {
                                            "$ref": "#/components/schemas/V1ReviewRequestSendMany"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "The existing request of the same `external_ref` (`meta.existing: true`)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/V1ReviewRequestSendOne"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/stats": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review request stats",
                "description": "Scope: `reviews:read`, company admins. Totals, per channel and per campaign for the requests created between `from` and `to` (YYYY-MM-DD).",
                "operationId": "v1ReviewRequestStats",
                "parameters": [
                    {
                        "name": "campaign",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequestStats"
                                        },
                                        "meta": {
                                            "properties": {
                                                "from": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "to": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "timezone": {
                                                    "type": "string"
                                                },
                                                "opens_tracked": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/{request}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a review request",
                "description": "Scope: `reviews:read`, company admins. One request with its contact, campaign and messages.",
                "operationId": "v1GetReviewRequest",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequest"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestPath"
                }
            ]
        },
        "/v1/companies/{company}/review-requests/{request}/cancel": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Cancel a review request",
                "description": "Scope: `reviews:write`, company admins. Cancels a scheduled or active request; 409 `not_cancellable` otherwise. No plan gate: it only stops sending, so it works while the location is locked.",
                "operationId": "v1CancelReviewRequest",
                "responses": {
                    "200": {
                        "description": "The canceled request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewRequest"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/V1ReviewRequestPath"
                }
            ]
        },
        "/v1/admin/review-sites/{slug}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a review site",
                "description": "Super admins, scope `companies:write`. One site of the catalog.",
                "operationId": "v1AdminGetReviewSite",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AdminReviewSite"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review site",
                "description": "Super admins, scope `companies:write`. Changes a site. Code-defined sites (`origin: config`) accept only `label`, `source_type`, `enabled`, `profile_patterns`, `display` and `notes`; catalog sites accept every field of POST, and a change of `hosts`, `actor_id`, `input_template`, `field_map` or `options` makes them unverified until the next verification run. `enabled: false` stops connecting, parsing and scheduling the site (existing sources stay).",
                "operationId": "v1AdminUpdateReviewSite",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "description": "At least one field. `slug` cannot change (prohibited).",
                                "properties": {
                                    "label": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "minLength": 1
                                    },
                                    "source_type": {
                                        "type": "string",
                                        "enum": [
                                            "customer_reviews",
                                            "employer_reviews",
                                            "directory",
                                            "aggregator"
                                        ]
                                    },
                                    "hosts": {
                                        "description": "Catalog sites only.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 100
                                        },
                                        "maxItems": 20,
                                        "minItems": 1
                                    },
                                    "profile_patterns": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 300
                                        },
                                        "maxItems": 10
                                    },
                                    "actor_id": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 191
                                    },
                                    "input_template": {
                                        "type": "object",
                                        "nullable": true,
                                        "additionalProperties": true
                                    },
                                    "field_map": {
                                        "type": "object",
                                        "nullable": true,
                                        "additionalProperties": true
                                    },
                                    "options": {
                                        "type": "object",
                                        "nullable": true,
                                        "additionalProperties": true
                                    },
                                    "display": {
                                        "description": "Display settings of the site (free-form).",
                                        "type": "object",
                                        "additionalProperties": true
                                    },
                                    "schedule_at": {
                                        "type": "string",
                                        "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                        "example": "02:40",
                                        "nullable": true
                                    },
                                    "enabled": {
                                        "type": "boolean"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 2000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AdminReviewSite"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "name": "slug",
                    "in": "path",
                    "description": "The site / driver name, e.g. `vagaro`.",
                    "required": true,
                    "schema": {
                        "type": "string"
                    }
                }
            ]
        },
        "/v1/companies/{company}/review-tags": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List review tags",
                "description": "Scope: `reviews:read`. The company's tags with `review_count` (reviews carrying it, removed reviews left out). `kind`: manual (made by people) or auto (made by grades.com: `topic:*`, `flag:*`, `service:*`). `meta.colors` lists the color tokens. Tags never name a person.",
                "operationId": "v1ReviewTags",
                "parameters": [
                    {
                        "name": "kind",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "manual",
                                "auto"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewTag"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "counts": {
                                                    "properties": {
                                                        "manual": {
                                                            "type": "integer"
                                                        },
                                                        "auto": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "colors": {
                                                    "description": "The color tokens.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "auto": {
                                                    "description": "Whether grades.com adds tags automatically.",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "limits": {
                                                    "properties": {
                                                        "manual": {
                                                            "description": "Most tags of your own.",
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "can": {
                                                    "description": "What the caller may do.",
                                                    "properties": {
                                                        "manage": {
                                                            "type": "boolean"
                                                        },
                                                        "apply": {
                                                            "type": "boolean"
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create a review tag",
                "description": "Scope: `reviews:write`; owners and admins. Body `{name, color?, description?}`. The slug comes from the name (`VIP customer` -> `vip-customer`). 409 `tag_exists`, 409 `tag_limit` (100 tags of your own). Never name a staff member in a tag.",
                "operationId": "v1CreateReviewTag",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "description": "Never a staff member's name.",
                                        "type": "string",
                                        "maxLength": 40
                                    },
                                    "color": {
                                        "description": "A color token (`meta.colors` of the list).",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 16
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 191
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewTag"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/review-tags/{tag}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Delete a review tag",
                "description": "Scope: `reviews:write`; owners and admins. Deletes a tag of your own; it leaves every review (history kept). 409 `auto_tag` for tags grades.com adds.",
                "operationId": "v1DeleteReviewTag",
                "parameters": [
                    {
                        "name": "tag",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "deleted": {
                                                    "type": "boolean"
                                                },
                                                "slug": {
                                                    "type": "string"
                                                },
                                                "removed_from": {
                                                    "description": "How many reviews the tag was taken off.",
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a review tag",
                "description": "Scope: `reviews:write`; owners and admins. `{tag}` = slug (URL-encoded) or id. Body `{name?, color?, description?}`; tags grades.com adds take a color only (409 `auto_tag`).",
                "operationId": "v1UpdateReviewTag",
                "parameters": [
                    {
                        "name": "tag",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "description": "Never a staff member's name.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 40
                                    },
                                    "color": {
                                        "description": "A color token (`meta.colors` of the list).",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 16
                                    },
                                    "description": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 191
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewTag"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/reviews/{review}/tags": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Tag a review",
                "description": "Scope: `reviews:write`. Body `{tags?: [slugs], sentiment?: positive|neutral|negative|mixed|null}`: puts the tags on the review (422 `unknown_tag`) and/or sets its sentiment (a person's value is never replaced automatically). Viewers: 403.",
                "operationId": "v1AddReviewTags",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "tags": {
                                        "description": "Tag slugs to put on the review: a list, or a comma-separated string.",
                                        "oneOf": [
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            },
                                            {
                                                "type": "string"
                                            }
                                        ]
                                    },
                                    "sentiment": {
                                        "description": "Sets the sentiment when present (null clears it).",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "positive",
                                            "neutral",
                                            "negative",
                                            "mixed"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewTagState"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/v1/companies/{company}/reviews/{review}/tags/{tag}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Remove a tag from a review",
                "description": "Scope: `reviews:write`. Takes the tag off the review. A tag grades.com added and a person took off is never put back.",
                "operationId": "v1RemoveReviewTag",
                "parameters": [
                    {
                        "name": "tag",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewTagState"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "$ref": "#/components/parameters/ReviewPath"
                }
            ]
        },
        "/v1/companies/{company}/reviews/tags/bulk": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Add or remove tags on many reviews",
                "description": "Scope: `reviews:write`. Body `{action: add|remove, tags: [slugs], reviews?: [uuids] | filters?: {tags, sentiment, start_date, end_date, source_drivers, min_rating, max_rating, has_company_response, s, removed}, dry_run?: bool}`. At most 500 uuids or 5,000 matched reviews (409 `too_many_reviews`). `dry_run` only counts.",
                "operationId": "v1BulkReviewTags",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "action",
                                    "tags"
                                ],
                                "properties": {
                                    "action": {
                                        "type": "string",
                                        "enum": [
                                            "add",
                                            "remove"
                                        ]
                                    },
                                    "tags": {
                                        "description": "Tag slugs: a list, or a comma-separated string (at least one).",
                                        "oneOf": [
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            },
                                            {
                                                "type": "string"
                                            }
                                        ]
                                    },
                                    "reviews": {
                                        "description": "Review uuids (at most 500); when given, `filters` is ignored.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "nullable": true
                                    },
                                    "filters": {
                                        "description": "Review list filters: tags, sentiment, start_date, end_date, source_drivers, min_rating, max_rating, has_company_response, s, removed (default exclude).",
                                        "type": "object",
                                        "nullable": true,
                                        "additionalProperties": true
                                    },
                                    "dry_run": {
                                        "description": "Only count.",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "action": {
                                                    "type": "string",
                                                    "enum": [
                                                        "add",
                                                        "remove"
                                                    ]
                                                },
                                                "tags": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "matched": {
                                                    "type": "integer"
                                                },
                                                "changed": {
                                                    "description": "Reviews changed (or, with `dry_run`, that would change).",
                                                    "type": "integer"
                                                },
                                                "dry_run": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/showcase": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review Showcase selection",
                "description": "Scope: `reviews:read`. A selection of the company's own reviews by rules: live, not hidden by the business, with text, never Yelp text, no platform the business left off its public pages, no personal data, no clinical terms for a healthcare business; newest first. `meta.excluded` counts what was left out and why. Never an average or `aggregateRating`. Not cached (the dashboard preview). `sites` naming `yelp` (JSON / Markdown only) needs `yelp_consent=true` (or a saved showcase that has it): without it 409 `yelp_consent_required` with the `warning` to show; HTML / JSON-LD never carry Yelp text.",
                "operationId": "v1Showcase",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ShowcaseCount"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMinRating"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMinLength"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMaxLength"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseTopic"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseSites"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMaxAge"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseLanguage"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseSeed"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseStyle"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseInclude"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseSaved"
                    },
                    {
                        "name": "yelp_consent",
                        "in": "query",
                        "description": "true = the caller confirms Yelp's terms (`warning` of the 409) for a selection that names Yelp in `sites`.",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (`format=json`; the other formats answer the raw document).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ShowcaseReview"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ShowcaseMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/showcases": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List saved showcases",
                "description": "Scope: `companies:read`. The company's saved showcases (oldest first) with their embed snippets.",
                "operationId": "v1ListShowcases",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewShowcase"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "limits": {
                                                    "description": "The plan's Review Showcase limits.",
                                                    "properties": {
                                                        "enabled": {
                                                            "type": "boolean"
                                                        },
                                                        "plan": {
                                                            "type": "string"
                                                        },
                                                        "max_reviews": {
                                                            "type": "integer"
                                                        },
                                                        "max_showcases": {
                                                            "type": "integer"
                                                        },
                                                        "refresh_minutes": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "script": {
                                                    "description": "The embed script URL.",
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Save a showcase",
                "description": "Scope: `companies:write`, company admins. Saves a showcase (name, style, rules). At most the plan's saved showcases (Starter 3, Pro 10, Premium 50): 409 `showcase_limit` beyond.",
                "operationId": "v1CreateShowcase",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name"
                                ],
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1ShowcaseInput"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created: `data` is a V1ReviewShowcase.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/showcases/{showcase}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a saved showcase",
                "description": "Scope: `companies:read`. One saved showcase, its embed snippets and its last changes (`meta.history`).",
                "operationId": "v1GetShowcase",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "properties": {
                                                "history": {
                                                    "description": "The last changes, newest first.",
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/V1SavedChange"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a saved showcase",
                "description": "Scope: `companies:write`, company admins. Changes the given fields; omitted rules keep their value. Embeds show the new rules at once (PATCH works the same).",
                "operationId": "v1UpdateShowcase",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ShowcaseInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: `data` is a V1ReviewShowcase.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Delete a saved showcase",
                "description": "Scope: `companies:write`, company admins. Deletes a saved showcase; its embeds answer 404 from then on (the history is kept).",
                "operationId": "v1DeleteShowcase",
                "responses": {
                    "204": {
                        "description": "Deleted"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a saved showcase",
                "description": "Same as PUT.",
                "operationId": "v1PatchShowcase",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1ShowcaseInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: `data` is a V1ReviewShowcase.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewShowcase"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "showcase",
                    "in": "path",
                    "description": "Saved showcase id (uuid).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/sources/requests": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List site requests",
                "description": "Scope: `companies:read`. The company's tracked site requests (docs/review-radar.md \"Tracked requests\"), newest first: the site, the status (`new`, `in_progress`, `live`, `not_possible`), the date it is due (two weeks after the request) and our answer. Requests the catalog connected at once are not listed (they are sources).",
                "operationId": "v1ListSiteRequests",
                "responses": {
                    "200": {
                        "description": "The requests",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SiteRequestCase"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "open": {
                                                    "type": "integer"
                                                },
                                                "promise_days": {
                                                    "type": "integer",
                                                    "example": 14
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Request a review site",
                "description": "Scope: `reviews:write`. Asks for a review site Grades does not offer yet, by the business's profile URL on it. When the catalog already serves the site (a live, URL-connected driver), the source is connected instead, with the same validation and plan checks as `POST /v1/companies/{company}/sources` (201; 200 `already_connected`). Otherwise the request is recorded and the site joins the demand queue (202). 422 codes: `own_site`, `oauth_required` (Google, Facebook: Review Sources), `not_allowed`, `not_a_review_site`; 429 `rate_limited` after 20 requests per company in 24 hours.",
                "operationId": "v1RequestReviewSite",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "url"
                                ],
                                "properties": {
                                    "url": {
                                        "description": "The business's page on the review site.",
                                        "type": "string",
                                        "format": "url",
                                        "example": "https://www.vagaro.com/yourbusiness"
                                    },
                                    "note": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 1000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Connected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SiteRequestResult"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Recorded: the site is in the demand queue",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SiteRequestResult"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/sources/{source}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Disconnect a review source",
                "description": "Scope: `reviews:write`. Disconnects the source, as in the dashboard (an OAuth grant no other source uses is revoked, stored credentials are wiped). Its reviews are not deleted: they leave the active lists and stay in the archive (`removal_reason: source_removed`); connecting the same site again brings them back as they are collected.",
                "operationId": "v1DisconnectSource",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "source",
                    "in": "path",
                    "description": "Source driver, e.g. `yelp` (a company has at most one source per driver).",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "example": "yelp"
                    }
                }
            ]
        },
        "/v1/companies/{company}/sources/{source}/reply-api": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Show a source's reply API connection",
                "description": "Scope: `companies:read`. Whether replies to this source's reviews are posted through the site's API with the company's own credentials (never returned).",
                "operationId": "v1ShowSourceReplyApi",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SourceReplyApi"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Connect a source's reply API",
                "description": "Scope: `reviews:write`, company admins. Stores the company's Trustpilot API key, secret and business user id after Trustpilot issued an access token for them (422 when it does not). From then on approved Trustpilot replies (and auto-posts, in `auto_positive` / `auto_all`) are published on Trustpilot instead of being stored for manual posting.",
                "operationId": "v1ConnectSourceReplyApi",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "api_key",
                                    "api_secret",
                                    "business_user_id"
                                ],
                                "properties": {
                                    "api_key": {
                                        "type": "string"
                                    },
                                    "api_secret": {
                                        "type": "string"
                                    },
                                    "business_user_id": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Connected",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SourceReplyApi"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Disconnect a source's reply API",
                "description": "Scope: `reviews:write`, company admins. Deletes the stored credentials; replies on the site are stored for manual posting again.",
                "operationId": "v1DisconnectSourceReplyApi",
                "responses": {
                    "204": {
                        "description": "Disconnected"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "source",
                    "in": "path",
                    "description": "Source driver. Only `trustpilot` has a reply API that takes company credentials.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "example": "trustpilot"
                    }
                }
            ]
        },
        "/v1/companies/{company}/strengths": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review strengths",
                "description": "Scope: `reviews:read`. What the business is praised for, read from its directory listing's stored review themes exactly as its public profile shows them: up to `max` (1-5, default 5) `strengths`, most mentioned first, each with `label`, `attribute`, the full `summary`, `mentions`, the profile's excerpt (`quote`: `text`, `author` as the profile shows reviewers, `site`, `date`, `date_display`, `review_uuid` when the caller can read that review; null where the profile shows none: Yelp and platforms the business does not feature are never quoted, nor a healthcare excerpt with a clinical term) and `cited_reviews` (uuids of the cited reviews readable through `GET .../reviews/{review}`, newest first, at most 20), plus `basis` (sites summarized, sites `excluded` from summaries, `from`/`to`, `reviews`, `window`, `line`, `generated_at`). A business without a listing or without themes gets 200 with `available: false` and `reason` `no_listing` / `no_themes`. No model is called. 409 for a directory-only company.",
                "operationId": "v1ReviewStrengths",
                "parameters": [
                    {
                        "name": "max",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 5,
                            "maximum": 5,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewStrengths"
                                        },
                                        "meta": {
                                            "required": [
                                                "source",
                                                "as_of"
                                            ],
                                            "properties": {
                                                "source": {
                                                    "type": "string",
                                                    "enum": [
                                                        "stored"
                                                    ]
                                                },
                                                "as_of": {
                                                    "type": "string",
                                                    "format": "date"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/members": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Team members with roles and locations",
                "description": "Scope: `companies:read`. The members of this business: for an HQ every person with a row on the HQ or one of its locations, for a location its own members and the HQ members whose all-locations row reaches it. `meta.roles` lists the roles the caller may give.",
                "operationId": "v1TeamMembers",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1TeamMember"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Invite a team member by role and locations",
                "description": "Scope: `companies:write`. Invites a person with a role to this business: `locations` \"all\" (the HQ and every location), a list of company uuids of this HQ (a row on each, no HQ row) or null (this company). One e-mail with one link that accepts all of them. Owners give any role anywhere; admins give approver and viewer on companies where they are admin (403 `role_forbidden` otherwise). 409 `already_member`; 422 `invalid_locations`; plan seat limit 402.",
                "operationId": "v1TeamInvite",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email",
                                    "role"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "name": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "role": {
                                        "type": "string",
                                        "enum": [
                                            "owner",
                                            "admin",
                                            "approver",
                                            "reviewer",
                                            "viewer"
                                        ]
                                    },
                                    "locations": {
                                        "description": "\"all\", a list of company uuids, or null.",
                                        "oneOf": [
                                            {
                                                "type": "string",
                                                "enum": [
                                                    "all"
                                                ]
                                            },
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                }
                                            },
                                            {
                                                "type": "object",
                                                "nullable": true,
                                                "enum": [
                                                    null
                                                ]
                                            }
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Invited",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1TeamMember"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/members/{user}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Remove a team member",
                "description": "Scope: `companies:write`. Removes the member's rows on this business (and, for an HQ, its locations) that the caller may manage. 409 `last_owner`, 409 `self`.",
                "operationId": "v1TeamRemove",
                "responses": {
                    "200": {
                        "description": "Removed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "removed"
                                            ],
                                            "properties": {
                                                "removed": {
                                                    "type": "boolean",
                                                    "enum": [
                                                        true
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Change a team member's role or locations",
                "description": "Scope: `companies:write`. Changes a member's `role` and / or `locations` (same values as the invitation; replaces the rows the caller may manage). Owners change anyone; admins approvers and viewers on their companies. 409 `last_owner` when the last owner would go.",
                "operationId": "v1TeamUpdate",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "role": {
                                        "type": "string",
                                        "enum": [
                                            "owner",
                                            "admin",
                                            "approver",
                                            "reviewer",
                                            "viewer"
                                        ]
                                    },
                                    "locations": {
                                        "description": "\"all\", a list of company uuids, or null."
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1TeamMember"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "user",
                    "in": "path",
                    "description": "User uuid.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/members/{user}/resend": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Resend a team invitation",
                "description": "Scope: `companies:write`. Sends the invitation of the member's pending rows again (one new link).",
                "operationId": "v1TeamResend",
                "responses": {
                    "200": {
                        "description": "Sent",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1TeamMember"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "user",
                    "in": "path",
                    "description": "User uuid.",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/v1/companies/{company}/permissions": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Your role and abilities here",
                "description": "Scope: `companies:read`. The caller's role in this company and what it allows (www/docs/roles.md).",
                "operationId": "v1CompanyPermissions",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "role": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "enum": [
                                                        "owner",
                                                        "super_admin",
                                                        "admin",
                                                        "approver",
                                                        "reviewer",
                                                        "viewer",
                                                        "user"
                                                    ]
                                                },
                                                "role_label": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "abilities": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                },
                                                "invitable_roles": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/widget": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review widget",
                "description": "Scope: `reviews:read`. One review widget: `preset` pill, strip, carousel, grid, list, masonry, spotlight, summary, wall, video, button, badge, popup or tab (the list with labels, review counts and display options is `meta.preset_info`), `theme` light|dark|auto, `lang` en|es, `accent` (hex color; none = the review page's accent, else #6b42fe), `count`, `min_rating` (default 1 = every rating), `sites`, `show_reply`. `meta.filter` says when the reviews are narrowed (the owner's notice); the rating and count never depend on it. The reviews follow the Review Showcase rules (never Yelp text, no platform the business does not feature, no review hidden from widgets, no clinical terms for a healthcare business, the plan's sites). `ref` = a publishable key or saved showcase id of this company to fill into `meta.embed` (else a placeholder). `include=html` adds the hosted page as `meta.rendered.html`.",
                "operationId": "v1Widget",
                "parameters": [
                    {
                        "name": "preset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pill",
                                "strip",
                                "carousel",
                                "grid",
                                "list",
                                "masonry",
                                "spotlight",
                                "summary",
                                "wall",
                                "video",
                                "badge",
                                "popup",
                                "tab",
                                "button"
                            ]
                        }
                    },
                    {
                        "name": "theme",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "light",
                                "dark",
                                "auto"
                            ]
                        }
                    },
                    {
                        "name": "accent",
                        "in": "query",
                        "description": "Hex color, e.g. %236b42fe.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "count",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 30,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "min_rating",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 5,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "sites",
                        "in": "query",
                        "description": "Comma-separated site keys, e.g. google,facebook,grades.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Language of the widget's own words (the reviews are shown as written).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es"
                            ]
                        }
                    },
                    {
                        "name": "columns",
                        "in": "query",
                        "description": "grid, masonry, wall: most columns (2-4, default 3).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                2,
                                3,
                                4
                            ]
                        }
                    },
                    {
                        "name": "autoplay",
                        "in": "query",
                        "description": "carousel, spotlight: on|off (default on).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "interval",
                        "in": "query",
                        "description": "carousel, spotlight, popup: seconds per review (4-20; default 6, 8, 10).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 20,
                            "minimum": 4
                        }
                    },
                    {
                        "name": "show_dates",
                        "in": "query",
                        "description": "on|off (default on).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_site",
                        "in": "query",
                        "description": "on|off: the review site's icon on each review (default on).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "position",
                        "in": "query",
                        "description": "badge, popup, tab: the side of the page (default right; popup left).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "left",
                                "right"
                            ]
                        }
                    },
                    {
                        "name": "mobile",
                        "in": "query",
                        "description": "popup: also on phones (default off).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "variant",
                        "in": "query",
                        "description": "pill: bordered|plain (default bordered).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "bordered",
                                "plain"
                            ]
                        }
                    },
                    {
                        "name": "panel",
                        "in": "query",
                        "description": "pill: on = a click opens a small panel of reviews instead of the link (default off).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_reply",
                        "in": "query",
                        "description": "carousel, grid, list, masonry, tab: the business's reply under each review (default off).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_grade",
                        "in": "query",
                        "description": "Display option (docs/widgets.md \"Display options\"): the Grades.com grade badge. Defaults per preset: `meta.preset_info[].defaults`.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_count",
                        "in": "query",
                        "description": "Display option: the review count.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_rating",
                        "in": "query",
                        "description": "Display option: the average.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "rating_decimals",
                        "in": "query",
                        "description": "Display option: 1 or 2 decimals of the average (pill default 1, others 2).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                2
                            ]
                        }
                    },
                    {
                        "name": "show_stars",
                        "in": "query",
                        "description": "Display option: the stars.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_rating_word",
                        "in": "query",
                        "description": "Display option: Excellent (4.5+), Great (4.0+), Good (3.5+), none under 10 reviews; describes the average, not an award.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_source_mark",
                        "in": "query",
                        "description": "Display option: the Grades.com mark, or the site's icon when `sites` names one site (the strip: the site icons).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "label",
                        "in": "query",
                        "description": "Display option: a caption up to 40 characters, plain text (replaces \"Reviews on grades.com\"; on the pill a leading caption). No links, e-mail addresses, markup or claims (\"all reviews\", \"verified\", ranks, awards): 422 `invalid_label`.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 40
                        }
                    },
                    {
                        "name": "show_summary",
                        "in": "query",
                        "description": "Widgets v2 (only while WIDGETS_V2_STATUS admits the company, else ignored): on = the approved AI summary line above the cards.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "controls",
                        "in": "query",
                        "description": "Widgets v2: visitor controls, comma list of sites, stars, sort (list, grid, masonry, tab; carousel and spotlight: sites only).",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "description": "Widgets v2: newest (default), highest or lowest.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "newest",
                                "highest",
                                "lowest"
                            ]
                        }
                    },
                    {
                        "name": "font",
                        "in": "query",
                        "description": "Widgets v2: inherit (default), manrope, system or serif.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "inherit",
                                "manrope",
                                "system",
                                "serif"
                            ]
                        }
                    },
                    {
                        "name": "radius",
                        "in": "query",
                        "description": "Widgets v2: corner radius 0-24 px (default 12).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 24,
                            "minimum": 0
                        }
                    },
                    {
                        "name": "card_style",
                        "in": "query",
                        "description": "Widgets v2: bordered (default), elevated or flat.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "bordered",
                                "elevated",
                                "flat"
                            ]
                        }
                    },
                    {
                        "name": "star_color",
                        "in": "query",
                        "description": "Widgets v2: hex color of the stars (fitted to 3:1 contrast).",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "translate",
                        "in": "query",
                        "description": "Widgets v2: on = reviews in another language than `lang` show a stored machine translation (see original).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "widget_id",
                        "in": "query",
                        "description": "Widgets v2: a saved widget of this company (its Premium custom CSS applies).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    },
                    {
                        "name": "v_site",
                        "in": "query",
                        "description": "Widgets v2 visitor param: a site tab (with controls=sites).",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "v_stars",
                        "in": "query",
                        "description": "Widgets v2 visitor param: lowest rating chosen (never below min_rating).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 5,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "v_sort",
                        "in": "query",
                        "description": "Widgets v2 visitor param: newest, highest or lowest.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "newest",
                                "highest",
                                "lowest"
                            ]
                        }
                    },
                    {
                        "name": "v_page",
                        "in": "query",
                        "description": "Widgets v2 visitor param: page of `count` reviews (1-20).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 20,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "ref",
                        "in": "query",
                        "description": "Publishable key or saved showcase id for the snippets.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "include",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "html"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` is the widget, `meta.embed` the snippets.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetData"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/widget-summary": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Widget AI summary",
                "description": "Scope: `reviews:read`. The AI summary header of the widgets (`show_summary`): `data.approved` (what widgets show), `data.draft` (newer than the approved one, awaiting the owner), `data.history` (every version, newest first). `lang` en|es. 404 while widgets v2 are off for the company.",
                "operationId": "v1WidgetSummary",
                "parameters": [
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryState"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Write the widget AI summary",
                "description": "Scope: `companies:write`, owners and admins. The owner's own line (`text`, at most 140 characters, plain text; no \"all/every reviews\", \"verified\", ranks or awards): a new approved version with model `manual`. 400 `body.text` for a missing or too long `text`; 422 `invalid_summary` for a line the summary rules refuse.",
                "operationId": "v1UpdateWidgetSummary",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "maxLength": 140
                                    },
                                    "lang": {
                                        "type": "string",
                                        "enum": [
                                            "en",
                                            "es"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: the summary state with the owner's line as the approved version.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryState"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/widget-summary/generate": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Generate the widget AI summary",
                "description": "Scope: `companies:write`, owners and admins. Asks for a new draft now (one model call from all the company's counted reviews; never Yelp text; healthcare text scrubbed) when the reviews changed since the last version, within the monthly budget. `meta.result`: created, unchanged, budget, failed or no_reviews; a failed call keeps the approved summary.",
                "operationId": "v1GenerateWidgetSummary",
                "parameters": [
                    {
                        "name": "lang",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (no request body): the summary state after the attempt; `meta.result` says what happened.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryState"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/widget-summary/{summary}/approve": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Approve the widget AI summary",
                "description": "Scope: `companies:write`, owners and admins. Approves a draft: widgets show it from now on (the previous approved version stays in the history).",
                "operationId": "v1ApproveWidgetSummary",
                "responses": {
                    "200": {
                        "description": "OK (no request body): the summary state in the draft's language.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryState"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "summary",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/companies/{company}/widget-summary/{summary}/reject": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Reject the widget AI summary",
                "description": "Scope: `companies:write`, owners and admins. Rejects a draft (kept in the history; the approved summary stays).",
                "operationId": "v1RejectWidgetSummary",
                "responses": {
                    "200": {
                        "description": "OK (no request body): the summary state in the draft's language.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryState"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "summary",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer"
                    }
                }
            ]
        },
        "/v1/companies/{company}/widgets": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Saved widgets",
                "description": "Scope: `companies:read`. The saved widgets (preset, settings = the snippet's options, Premium custom CSS). A snippet names one with `widget_id`.",
                "operationId": "v1SavedWidgets",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SavedWidget"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "custom_css": {
                                                    "description": "Whether the plan draws custom CSS (Premium) and its size limit.",
                                                    "properties": {
                                                        "allowed": {
                                                            "type": "boolean"
                                                        },
                                                        "plan_required": {
                                                            "type": "string",
                                                            "enum": [
                                                                "premium"
                                                            ]
                                                        },
                                                        "max_bytes": {
                                                            "type": "integer"
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Save a widget",
                "description": "Scope: `companies:write`, owners and admins. Saves a widget: `name`, `preset`, `settings` (options as in the snippet, stored as their non-default values) and `custom_css` (Premium: 402 otherwise; at most 4 KB; no @import, no url() except data: images, no expression, no \"<\", no position: fixed outside floating presets: 422 `invalid_custom_css`).",
                "operationId": "v1CreateSavedWidget",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name",
                                    "preset"
                                ],
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1SavedWidgetInput"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SavedWidget"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/v1/companies/{company}/widgets/{widget}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get a saved widget",
                "description": "Scope: `companies:read`. One saved widget and its last changes (`meta.history`).",
                "operationId": "v1SavedWidget",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SavedWidget"
                                        },
                                        "meta": {
                                            "properties": {
                                                "history": {
                                                    "description": "The last 50 changes, newest first.",
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/V1SavedChange"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a saved widget",
                "description": "Scope: `companies:write`, owners and admins. Changes the given fields (same rules as when saving).",
                "operationId": "v1UpdateSavedWidget",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/V1SavedWidgetInput"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1SavedWidget"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Delete a saved widget",
                "description": "Scope: `companies:write`, owners and admins. Deletes a saved widget (history kept); snippets naming it lose its custom CSS.",
                "operationId": "v1DeleteSavedWidget",
                "responses": {
                    "204": {
                        "description": "Deleted"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                },
                {
                    "name": "widget",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            ]
        },
        "/company/{company}/widget": {
            "get": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Review widget",
                "description": "Dashboard session version of `GET /v1/companies/{company}/widget`.",
                "operationId": "widget",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetData"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/widget-summary": {
            "get": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Widget AI summary",
                "description": "Dashboard session version of `GET /v1/companies/{company}/widget-summary` (also generate, approve, reject and PUT).",
                "operationId": "widgetSummary",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryState"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1WidgetSummaryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company/{company}/widgets": {
            "get": {
                "tags": [
                    "Showcase"
                ],
                "summary": "Saved widgets",
                "description": "Dashboard session version of `GET /v1/companies/{company}/widgets` (also POST, GET / PUT / DELETE one).",
                "operationId": "savedWidgets",
                "responses": {
                    "200": {
                        "description": "OK: the same `meta.custom_css` as the v1 list.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SavedWidget"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "custom_css": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            },
            "parameters": [
                {
                    "$ref": "#/components/parameters/CompanyPath"
                }
            ]
        },
        "/company": {
            "post": {
                "tags": [
                    "Company"
                ],
                "summary": "Create company",
                "description": "<\\<Description>>",
                "operationId": "createCompany",
                "requestBody": {
                    "$ref": "#/components/requestBodies/CreateCompanyRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Company"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "422": {
                        "$ref": "#/components/responses/CompanyAlreadyExists"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/company/{company}/reviews/{review}/handling": {
            "get": {
                "tags": [
                    "Reviews"
                ],
                "summary": "How a review is replied to and reported",
                "description": "Dashboard session version of `GET /v1/companies/{company}/reviews/{review}/handling`.",
                "operationId": "reviewHandling",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewPath"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "reply": {
                                                    "$ref": "#/components/schemas/V1ReviewHandling"
                                                },
                                                "report": {
                                                    "$ref": "#/components/schemas/V1ReviewHandling"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/company/{company}/sources/handling": {
            "get": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "How each connected review site is handled",
                "description": "Dashboard session version of `GET /v1/companies/{company}/sources/handling`.",
                "operationId": "sourcesHandling",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SourceHandling"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/company/{company}/reviews-source/direct/reviews/import": {
            "post": {
                "tags": [
                    "ReviewsSource"
                ],
                "summary": "Import direct reviews from CSV",
                "description": "<\\<Description>>",
                "operationId": "importReviews",
                "requestBody": {
                    "$ref": "#/components/requestBodies/ReviewsImportRequestBody"
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/ImportReviews"
                    },
                    "400": {
                        "$ref": "#/components/responses/ValidateError"
                    },
                    "401": {
                        "$ref": "#/components/responses/AuthorizationError"
                    },
                    "404": {
                        "$ref": "#/components/responses/CompanyNotFound"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": [
                    {
                        "dashboardSession": []
                    }
                ]
            }
        },
        "/user/logout": {
            "post": {
                "tags": [
                    "User"
                ],
                "summary": "Logout user",
                "description": "<\\<Description>>",
                "operationId": "userLogout",
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Successfully"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalServerError"
                    }
                },
                "security": []
            }
        },
        "/v1/agencies/{agency}/clients": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "List an agency's clients",
                "description": "Scope: `companies:read`; accepted members (without `all_clients`: only their assigned clients). Client businesses by name with plan, billing state, locations, review stats for the period (`from`/`to`, UTC dates, default the last 30 days) over the client and its locations, and the latest AI Reputation run. `q` filters by name; `page`, `per_page` (50, max 200).",
                "operationId": "v1ListAgencyClients",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AgencyClient"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "from",
                                                "to",
                                                "count",
                                                "total",
                                                "page",
                                                "per_page",
                                                "totals"
                                            ],
                                            "properties": {
                                                "from": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "to": {
                                                    "description": "Inclusive.",
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "page": {
                                                    "type": "integer"
                                                },
                                                "per_page": {
                                                    "type": "integer"
                                                },
                                                "totals": {
                                                    "description": "Over the clients of this page; null when there are none.",
                                                    "nullable": true,
                                                    "allOf": [
                                                        {
                                                            "$ref": "#/components/schemas/V1AgencyClientTotals"
                                                        }
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Add a client (attach or request)",
                "description": "Scope: `companies:write`; agency admins. `{company: uuid, plan?, message?}`. 201 with the client row when the caller is an accepted admin of that business directly (or a platform super admin); 202 with a pending request otherwise (the business's admins accept it in their dashboard).",
                "operationId": "v1AttachAgencyClient",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "company"
                                ],
                                "properties": {
                                    "company": {
                                        "description": "The business uuid.",
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "plan": {
                                        "description": "One of the agency's plans; default its default plan.",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "starter",
                                            "pro",
                                            "premium"
                                        ]
                                    },
                                    "message": {
                                        "description": "Shown to the business's admins with a request.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 500
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Attached: the client row.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyClient"
                                        },
                                        "meta": {
                                            "required": [
                                                "status"
                                            ],
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "attached"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Requested: the pending request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyClientRequest"
                                        },
                                        "meta": {
                                            "required": [
                                                "status"
                                            ],
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "pending"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/clients/{company}": {
            "delete": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Remove a client",
                "description": "Scope: `companies:write`; agency admins. The business leaves the agency: it keeps its account and data and the agency plan for the grace period, then pays list price on its own billing.",
                "operationId": "v1DetachAgencyClient",
                "responses": {
                    "204": {
                        "description": "Removed"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Change a client's plan",
                "description": "Scope: `companies:write`; agency admins. `{plan}`: one of the agency's plans.",
                "operationId": "v1UpdateAgencyClient",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "plan"
                                ],
                                "properties": {
                                    "plan": {
                                        "type": "string",
                                        "enum": [
                                            "starter",
                                            "pro",
                                            "premium"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK: the client row.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyClient"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/client-requests": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "List an agency's client requests",
                "description": "Scope: `companies:read`; agency admins. Requests to take on businesses (`status`, default `pending`).",
                "operationId": "v1ListAgencyClientRequests",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AgencyClientRequest"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count",
                                                "status"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "pending",
                                                        "accepted",
                                                        "declined",
                                                        "cancelled",
                                                        "expired",
                                                        "all"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/agencies/{agency}/client-requests/{request}": {
            "delete": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Cancel a client request",
                "description": "Scope: `companies:write`; agency admins. Cancels a pending request.",
                "operationId": "v1CancelAgencyClientRequest",
                "responses": {
                    "200": {
                        "description": "OK: the canceled request.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyClientRequest"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/billing": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Agency billing",
                "description": "Scope: `companies:read`; agency admins. The agency's bill: lines per plan (base and extra locations), agency prices, clients not billed and why, checkout and portal availability.",
                "operationId": "v1AgencyBilling",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyBilling"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/agencies/{agency}/billing/checkout": {
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Start the agency subscription",
                "description": "Scope: `companies:write`; agency admins. `{interval: monthly|yearly}` -> `{url}` of a Stripe Checkout for the agency subscription.",
                "operationId": "v1AgencyCheckout",
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "interval": {
                                        "description": "Default `monthly`.",
                                        "type": "string",
                                        "enum": [
                                            "monthly",
                                            "yearly"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "url"
                                            ],
                                            "properties": {
                                                "url": {
                                                    "description": "The Stripe Checkout page.",
                                                    "type": "string",
                                                    "format": "uri"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/billing/portal": {
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Agency billing portal",
                "description": "Scope: `companies:write`; agency admins. `{url}` of the Stripe Customer Portal of the agency's billing company.",
                "operationId": "v1AgencyPortal",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "url"
                                            ],
                                            "properties": {
                                                "url": {
                                                    "description": "The Stripe Customer Portal.",
                                                    "type": "string",
                                                    "format": "uri"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "List agencies",
                "description": "Scope: `companies:read`. The caller's agencies (accepted and pending memberships); `all=1` lists every agency for platform super admins.",
                "operationId": "v1ListAgencies",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1Agency"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Create an agency",
                "description": "Scope: `companies:write`; platform super admins only. `{name, slug?, owner_email, allowed_plans?, default_plan?, billing_company?, hub?}`. The owner becomes an accepted admin.",
                "operationId": "v1CreateAgency",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "name",
                                    "owner_email"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191
                                    },
                                    "slug": {
                                        "description": "Lower-case letters, digits and dashes; default: from the name. 409 `slug_taken`.",
                                        "type": "string",
                                        "pattern": "^[a-z0-9][a-z0-9-]*$",
                                        "nullable": true,
                                        "maxLength": 64
                                    },
                                    "owner_email": {
                                        "description": "An existing grades.com user; becomes an accepted admin.",
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191
                                    },
                                    "allowed_plans": {
                                        "description": "The plans the agency sells; null or empty = every plan.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "starter",
                                                "pro",
                                                "premium"
                                            ]
                                        },
                                        "nullable": true
                                    },
                                    "default_plan": {
                                        "type": "string",
                                        "enum": [
                                            "starter",
                                            "pro",
                                            "premium"
                                        ]
                                    },
                                    "billing_company": {
                                        "description": "Uuid of the business that holds the agency subscription.",
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    },
                                    "hub": {
                                        "description": "The Client Hub's agency (only one; 409 `hub_agency_exists`).",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Agency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Get an agency",
                "description": "Scope: `companies:read`. The agency (uuid or slug) for a member.",
                "operationId": "v1GetAgency",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Agency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "patch": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Update an agency",
                "description": "Scope: `companies:write`. Agency admins: `name`, `default_plan`, `white_label_host` (clears the verification). Platform super admins also: `slug`, `status`, `allowed_plans`, `billing_company`, `hub`, `white_label_verified`.",
                "operationId": "v1UpdateAgency",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "maxLength": 191
                                    },
                                    "default_plan": {
                                        "type": "string",
                                        "enum": [
                                            "starter",
                                            "pro",
                                            "premium"
                                        ]
                                    },
                                    "white_label_host": {
                                        "description": "A host name on the agency's own domain; null or \"\" clears it. A change clears the verification.",
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 191
                                    },
                                    "slug": {
                                        "description": "Platform super admins only.",
                                        "type": "string",
                                        "pattern": "^[a-z0-9][a-z0-9-]*$",
                                        "maxLength": 64
                                    },
                                    "status": {
                                        "description": "Platform super admins only.",
                                        "type": "string",
                                        "enum": [
                                            "active",
                                            "suspended"
                                        ]
                                    },
                                    "allowed_plans": {
                                        "description": "Platform super admins only; null or empty = every plan.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "starter",
                                                "pro",
                                                "premium"
                                            ]
                                        },
                                        "nullable": true
                                    },
                                    "billing_company": {
                                        "description": "Platform super admins only; uuid of a business, null clears it.",
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    },
                                    "hub": {
                                        "description": "Platform super admins only.",
                                        "type": "boolean"
                                    },
                                    "white_label_verified": {
                                        "description": "Platform super admins only.",
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Agency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/accept": {
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Accept an agency invitation",
                "description": "Scope: `companies:write`. The caller accepts their pending membership of the agency.",
                "operationId": "v1AcceptAgencyMembership",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Agency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/members": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "List agency members",
                "description": "Scope: `companies:read`. Members (accepted and pending), admins first.",
                "operationId": "v1ListAgencyMembers",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AgencyMember"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Add an agency member",
                "description": "Scope: `companies:write`; agency admins. `{email, role: admin|member, all_clients?, clients?}` (`clients`: client business uuids for a member without all clients). An existing grades.com user: 201 with the member row (`meta.status = member`), pending until they accept (`POST .../accept`), and an e-mail. Anyone else: 202 with an invitation (`meta.status = invited`) e-mailed with a sign-up link.",
                "operationId": "v1AddAgencyMember",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "maxLength": 191
                                    },
                                    "role": {
                                        "description": "Default `member`.",
                                        "type": "string",
                                        "enum": [
                                            "admin",
                                            "member"
                                        ]
                                    },
                                    "all_clients": {
                                        "description": "Default true.",
                                        "type": "boolean"
                                    },
                                    "clients": {
                                        "description": "Client business uuids, for a member without all clients.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "maxItems": 500
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Added: the member row (pending until they accept).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyMember"
                                        },
                                        "meta": {
                                            "required": [
                                                "status"
                                            ],
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "member"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Invited: the e-mail invitation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyInvitation"
                                        },
                                        "meta": {
                                            "required": [
                                                "status"
                                            ],
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "invited"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/members/{user}": {
            "delete": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Remove an agency member",
                "description": "Scope: `companies:write`. Agency admins remove a member; a member may remove themselves. The last admin can't leave.",
                "operationId": "v1RemoveAgencyMember",
                "responses": {
                    "204": {
                        "description": "Removed"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "patch": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Update an agency member",
                "description": "Scope: `companies:write`; agency admins. `{role?, role_on_clients?, all_clients?, clients?}` (`role_on_clients`: owner|admin|approver|viewer on the clients, null = default: admin -> owner, member -> legacy member; www/docs/roles.md; `clients` replaces the client businesses assigned to a member without all clients); the last admin can't be demoted.",
                "operationId": "v1UpdateAgencyMember",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "role": {
                                        "type": "string",
                                        "enum": [
                                            "admin",
                                            "member"
                                        ]
                                    },
                                    "role_on_clients": {
                                        "description": "null = the default of the agency role.",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "owner",
                                            "admin",
                                            "approver",
                                            "reviewer",
                                            "viewer"
                                        ]
                                    },
                                    "all_clients": {
                                        "type": "boolean"
                                    },
                                    "clients": {
                                        "description": "Replaces the client businesses (uuids) assigned to a member without all clients.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "maxItems": 500
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyMember"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/invitations": {
            "get": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "List agency invitations",
                "description": "Scope: `companies:read`; agency admins. E-mail invitations of people without an account (`status`: pending (default), accepted, revoked, expired or all). Never the link.",
                "operationId": "v1ListAgencyInvitations",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AgencyInvitation"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/agencies/{agency}/invitations/{invitation}/resend": {
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Resend an agency invitation",
                "description": "Scope: `companies:write`; agency admins. E-mails a pending (or expired) invitation again with a new link and a new expiry; the old link stops working.",
                "operationId": "v1ResendAgencyInvitation",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgencyInvitation"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/agencies/{agency}/invitations/{invitation}": {
            "delete": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Revoke an agency invitation",
                "description": "Scope: `companies:write`; agency admins. Revokes an invitation: its link stops working.",
                "operationId": "v1RevokeAgencyInvitation",
                "responses": {
                    "204": {
                        "description": "Revoked"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/companies/{company}/agent/locks": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Locked review agent rules",
                "description": "Scope: `companies:read`. The review agent rule parts locked for this company by its HQ (at a location) or for its locations (at an HQ).",
                "operationId": "v1AgentLocks",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLocks"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Lock review agent rules for the locations",
                "description": "Scope: `companies:write`. An HQ's owners lock review agent rule parts for every location: `locked` replaces the list (`approval.*` and `report_rules.*` cover both approval parts / the report rules). A locked part can only be changed at a location by the HQ's owners (403 `locked_by_hq` on the settings write). Every lock and unlock is recorded. 403 `role_forbidden` for other roles; 409 `not_an_hq` without locations.",
                "operationId": "v1UpdateAgentLocks",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "locked"
                                ],
                                "properties": {
                                    "locked": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentLocks"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/companies/{company}/agent/approvers": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Review agent approvers",
                "description": "Scope: `companies:read`. Who approves the review agent's actions here: the people assigned, who gets the approval notices (`routing`) and who can be assigned.",
                "operationId": "v1AgentApprovers",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentApprovers"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "put": {
                "tags": [
                    "v1"
                ],
                "summary": "Choose who approves the review agent's actions",
                "description": "Scope: `companies:write`. Owners and admins choose who approves here: `users` (uuids of members who can approve: owner, admin or approver) replaces the list; an empty list sends the notices to the owners and admins again (then the HQ's owners). 403 `role_forbidden` for other roles, 422 `invalid_approvers`.",
                "operationId": "v1UpdateAgentApprovers",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "users"
                                ],
                                "properties": {
                                    "users": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "format": "uuid"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AgentApprovers"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/internal/browser-jobs/claim": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Claim a browser job",
                "description": "Claims the next due job (lease 300 s), waiting up to `wait` seconds (long poll). 204 when nothing is due. 409 `worker_busy` when this `X-Worker-Id` already holds a job. The job says whose account it runs with (`session_scope`: `company` or `platform`, a Grades-owned reporter account). `features`: what the worker can do; only a worker sending `report_rehearsal` gets report jobs with `payload.rehearsal: true` (stop before the final submit, end with outcome `rehearsed`).",
                "operationId": "v1InternalClaimBrowserJob",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "kind": {
                                        "type": "string",
                                        "enum": [
                                            "reply",
                                            "report_review",
                                            "login_check"
                                        ]
                                    },
                                    "site": {
                                        "type": "string",
                                        "example": "yelp"
                                    },
                                    "wait": {
                                        "type": "integer",
                                        "maximum": 20,
                                        "minimum": 0
                                    },
                                    "features": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "example": "report_rehearsal"
                                        }
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The job (see the worker contract; `BrowserJobPresenter::forWorker()`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "uuid",
                                                "kind",
                                                "site",
                                                "attempt",
                                                "max_attempts",
                                                "lease_expires_at",
                                                "session_scope",
                                                "company",
                                                "session",
                                                "review",
                                                "payload",
                                                "action"
                                            ],
                                            "properties": {
                                                "uuid": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "kind": {
                                                    "type": "string",
                                                    "enum": [
                                                        "reply",
                                                        "report_review",
                                                        "login_check"
                                                    ]
                                                },
                                                "site": {
                                                    "type": "string"
                                                },
                                                "attempt": {
                                                    "type": "integer"
                                                },
                                                "max_attempts": {
                                                    "type": "integer"
                                                },
                                                "lease_expires_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "session_scope": {
                                                    "type": "string",
                                                    "enum": [
                                                        "company",
                                                        "platform"
                                                    ]
                                                },
                                                "company": {
                                                    "properties": {
                                                        "uuid": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "session": {
                                                    "properties": {
                                                        "uuid": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "site": {
                                                            "type": "string"
                                                        },
                                                        "scope": {
                                                            "type": "string",
                                                            "enum": [
                                                                "company",
                                                                "platform"
                                                            ]
                                                        },
                                                        "account_label": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "user_agent": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "proxy_session": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "sealed_state": {
                                                            "description": "Opaque sealed session of the account (secret; never logged).",
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "site_actions_24h": {
                                                            "type": "integer"
                                                        },
                                                        "geo": {
                                                            "description": "Where the business is, for the residential proxy; null for a Grades-owned account.",
                                                            "properties": {
                                                                "country": {
                                                                    "type": "string"
                                                                },
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true
                                                                },
                                                                "city": {
                                                                    "type": "string",
                                                                    "nullable": true
                                                                }
                                                            },
                                                            "type": "object",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "review": {
                                                    "properties": {
                                                        "uuid": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "external_url": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "public_url": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "page_url": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "system_id": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "username": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "rating": {
                                                            "type": "integer",
                                                            "nullable": true
                                                        },
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "published_date": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "payload": {
                                                    "description": "What to do, by kind (reply text, report reason, `rehearsal`; the worker contract).",
                                                    "type": "object",
                                                    "additionalProperties": true
                                                },
                                                "action": {
                                                    "properties": {
                                                        "uuid": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "204": {
                        "description": "Nothing to do"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "503": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-jobs/{job}/heartbeat": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Extend a browser job lease",
                "description": "Extends the lease. `cancel: true`: the session was disconnected; stop and call `fail` with `canceled`. 409 `lease_lost` when the job is not held by this worker any more.",
                "operationId": "v1InternalBrowserJobHeartbeat",
                "parameters": [
                    {
                        "name": "job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Lease extended",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "lease_expires_at",
                                                "cancel"
                                            ],
                                            "properties": {
                                                "lease_expires_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "cancel": {
                                                    "description": "The session was disconnected: stop and fail the job with `canceled`.",
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-jobs/{job}/evidence": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Get an evidence upload target",
                "description": "Names the object for one piece of evidence and, when the app can sign, returns a signed PUT URL (`upload.url`, send `upload.headers`). With `upload.url` null the worker uploads with its own identity.",
                "operationId": "v1InternalBrowserJobEvidence",
                "parameters": [
                    {
                        "name": "job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "kind",
                                    "content_type"
                                ],
                                "properties": {
                                    "kind": {
                                        "type": "string",
                                        "enum": [
                                            "before",
                                            "after",
                                            "html",
                                            "error",
                                            "rehearsal"
                                        ]
                                    },
                                    "content_type": {
                                        "type": "string",
                                        "enum": [
                                            "image/png",
                                            "image/jpeg",
                                            "text/html",
                                            "application/json"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The upload target",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "object_name",
                                                "bucket",
                                                "upload"
                                            ],
                                            "properties": {
                                                "object_name": {
                                                    "type": "string"
                                                },
                                                "bucket": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "upload": {
                                                    "required": [
                                                        "method",
                                                        "url",
                                                        "headers",
                                                        "expires_at"
                                                    ],
                                                    "properties": {
                                                        "method": {
                                                            "type": "string",
                                                            "enum": [
                                                                "PUT"
                                                            ]
                                                        },
                                                        "url": {
                                                            "description": "Signed PUT URL; null: upload with the worker's own identity.",
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "headers": {
                                                            "properties": {
                                                                "Content-Type": {
                                                                    "type": "string"
                                                                }
                                                            },
                                                            "type": "object"
                                                        },
                                                        "expires_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-jobs/{job}/complete": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Complete a browser job",
                "description": "Records success: `result{outcome, external_reference?, posted_text?, account_label?, notes?}`, the evidence uploaded and optionally the refreshed sealed state. A report job may also end `rehearsed` (stopped before the final submit, nothing filed) with `result.rehearsal{stopped_before, fields[{label, type, value}], form_text}`: the job becomes `rehearsed`, never `succeeded`.",
                "operationId": "v1InternalCompleteBrowserJob",
                "parameters": [
                    {
                        "name": "job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "result"
                                ],
                                "properties": {
                                    "result": {
                                        "required": [
                                            "outcome"
                                        ],
                                        "properties": {
                                            "outcome": {
                                                "description": "`posted` (reply), `reported` or `rehearsed` (report_review), `logged_in` (login_check).",
                                                "type": "string",
                                                "enum": [
                                                    "posted",
                                                    "reported",
                                                    "logged_in",
                                                    "rehearsed"
                                                ]
                                            },
                                            "external_reference": {
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 255
                                            },
                                            "posted_text": {
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 5000
                                            },
                                            "account_label": {
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 255
                                            },
                                            "notes": {
                                                "type": "string",
                                                "nullable": true,
                                                "maxLength": 1000
                                            },
                                            "rehearsal": {
                                                "required": [
                                                    "stopped_before"
                                                ],
                                                "properties": {
                                                    "stopped_before": {
                                                        "type": "string",
                                                        "maxLength": 200
                                                    },
                                                    "form_text": {
                                                        "type": "string",
                                                        "nullable": true,
                                                        "maxLength": 2000
                                                    },
                                                    "fields": {
                                                        "type": "array",
                                                        "items": {
                                                            "required": [
                                                                "label",
                                                                "type",
                                                                "value"
                                                            ],
                                                            "properties": {
                                                                "label": {
                                                                    "type": "string",
                                                                    "maxLength": 200
                                                                },
                                                                "type": {
                                                                    "type": "string",
                                                                    "maxLength": 40
                                                                },
                                                                "value": {
                                                                    "type": "string",
                                                                    "nullable": true,
                                                                    "maxLength": 5000
                                                                }
                                                            },
                                                            "type": "object"
                                                        },
                                                        "maxItems": 40
                                                    }
                                                },
                                                "type": "object",
                                                "nullable": true
                                            }
                                        },
                                        "type": "object"
                                    },
                                    "evidence": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/components/schemas/V1BrowserEvidenceEntry"
                                        },
                                        "maxItems": 10
                                    },
                                    "state": {
                                        "description": "The refreshed session, when the site renewed it.",
                                        "required": [
                                            "sealed_state"
                                        ],
                                        "properties": {
                                            "sealed_state": {
                                                "description": "Opaque sealed session (secret; never logged).",
                                                "type": "string",
                                                "maxLength": 524288
                                            },
                                            "expires_at": {
                                                "type": "string",
                                                "format": "date-time",
                                                "nullable": true
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Recorded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1BrowserJobStatus"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-jobs/{job}/fail": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Fail a browser job",
                "description": "Records a failure. `login_required`, `captcha`, `two_factor` end as `needs_owner` (never retried); other codes are retried with backoff while `retryable` and attempts remain.",
                "operationId": "v1InternalFailBrowserJob",
                "parameters": [
                    {
                        "name": "job",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "error_code",
                                    "message",
                                    "retryable"
                                ],
                                "properties": {
                                    "error_code": {
                                        "type": "string",
                                        "enum": [
                                            "login_required",
                                            "captcha",
                                            "two_factor",
                                            "selector_missing",
                                            "review_not_found",
                                            "already_replied",
                                            "site_error",
                                            "rate_limited",
                                            "network",
                                            "canceled",
                                            "internal"
                                        ]
                                    },
                                    "message": {
                                        "type": "string",
                                        "maxLength": 500
                                    },
                                    "retryable": {
                                        "type": "boolean"
                                    },
                                    "evidence": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/components/schemas/V1BrowserEvidenceEntry"
                                        },
                                        "maxItems": 10
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Recorded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "uuid",
                                                "status",
                                                "retry_at"
                                            ],
                                            "properties": {
                                                "uuid": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "queued",
                                                        "claimed",
                                                        "succeeded",
                                                        "failed",
                                                        "needs_owner",
                                                        "canceled",
                                                        "rehearsed"
                                                    ]
                                                },
                                                "retry_at": {
                                                    "description": "When the job runs again (status `queued`), else null.",
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-sessions/connect": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Resolve a connect token",
                "description": "Exchanges a one-time connect token (from the live sign-in page URL fragment, or sent by the dashboard over the WebSocket for shared sign-in details) for the connect attempt. The token is consumed; the attempt becomes `in_progress`, held by this worker id until `deadline_at`. 404 when unknown, used, expired or canceled. 409 `method_mismatch` when `method` differs from the method of the attempt (the attempt fails).",
                "operationId": "v1InternalResolveBrowserConnect",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "token"
                                ],
                                "properties": {
                                    "token": {
                                        "type": "string"
                                    },
                                    "method": {
                                        "type": "string",
                                        "enum": [
                                            "live",
                                            "credentials"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The attempt, the session to sign in to and the company (null for a Grades-owned account)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "attempt",
                                                "scope",
                                                "session",
                                                "company",
                                                "expires_at"
                                            ],
                                            "properties": {
                                                "attempt": {
                                                    "required": [
                                                        "uuid",
                                                        "method",
                                                        "deadline_at"
                                                    ],
                                                    "properties": {
                                                        "uuid": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "method": {
                                                            "type": "string",
                                                            "enum": [
                                                                "live",
                                                                "credentials"
                                                            ]
                                                        },
                                                        "deadline_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "scope": {
                                                    "type": "string",
                                                    "enum": [
                                                        "company",
                                                        "platform"
                                                    ]
                                                },
                                                "session": {
                                                    "required": [
                                                        "uuid",
                                                        "site",
                                                        "scope",
                                                        "account_label",
                                                        "user_agent",
                                                        "proxy_session",
                                                        "geo"
                                                    ],
                                                    "properties": {
                                                        "uuid": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "site": {
                                                            "type": "string"
                                                        },
                                                        "scope": {
                                                            "type": "string",
                                                            "enum": [
                                                                "company",
                                                                "platform"
                                                            ]
                                                        },
                                                        "account_label": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "user_agent": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "proxy_session": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "geo": {
                                                            "description": "Where the business is, for the residential proxy; null for a Grades-owned account.",
                                                            "required": [
                                                                "country",
                                                                "state",
                                                                "city"
                                                            ],
                                                            "properties": {
                                                                "country": {
                                                                    "type": "string",
                                                                    "example": "us"
                                                                },
                                                                "state": {
                                                                    "type": "string",
                                                                    "nullable": true
                                                                },
                                                                "city": {
                                                                    "type": "string",
                                                                    "nullable": true
                                                                }
                                                            },
                                                            "type": "object",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "company": {
                                                    "required": [
                                                        "uuid",
                                                        "name"
                                                    ],
                                                    "properties": {
                                                        "uuid": {
                                                            "type": "string",
                                                            "format": "uuid"
                                                        },
                                                        "name": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "expires_at": {
                                                    "description": "Same as `attempt.deadline_at`.",
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-connect/{attempt}/heartbeat": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Keep a connect attempt alive",
                "description": "The worker is still working on the attempt (send every 30 s and on status changes; `needs_code` while waiting for a verification code). `cancel: true`: the attempt was canceled or expired, or the account was disconnected; close the browser. 409 `lease_lost` when another worker holds it. Without a heartbeat for 120 s the attempt expires.",
                "operationId": "v1InternalBrowserConnectHeartbeat",
                "parameters": [
                    {
                        "name": "attempt",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "in_progress",
                                            "needs_code"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Still held",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "cancel",
                                                "deadline_at"
                                            ],
                                            "properties": {
                                                "cancel": {
                                                    "description": "The attempt was canceled or expired, or the account disconnected: close the browser.",
                                                    "type": "boolean"
                                                },
                                                "deadline_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-connect/{attempt}/fail": {
            "post": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Fail a connect attempt",
                "description": "The worker ends the attempt without a session: `canceled` ends it as canceled, every other code as failed. `message` is shown to the user; never credentials or codes. Idempotent once finished.",
                "operationId": "v1InternalFailBrowserConnect",
                "parameters": [
                    {
                        "name": "attempt",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "error_code",
                                    "message"
                                ],
                                "properties": {
                                    "error_code": {
                                        "type": "string",
                                        "enum": [
                                            "captcha",
                                            "invalid_credentials",
                                            "two_factor_failed",
                                            "login_timeout",
                                            "abandoned",
                                            "canceled",
                                            "site_error",
                                            "network",
                                            "credentials_unreadable",
                                            "internal"
                                        ]
                                    },
                                    "message": {
                                        "type": "string",
                                        "maxLength": 500
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The attempt's final status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "uuid",
                                                "status"
                                            ],
                                            "properties": {
                                                "uuid": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "pending",
                                                        "in_progress",
                                                        "needs_code",
                                                        "succeeded",
                                                        "failed",
                                                        "expired",
                                                        "canceled"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/internal/browser-sessions/{session}/state": {
            "put": {
                "tags": [
                    "v1 internal"
                ],
                "summary": "Store a sealed browser session",
                "description": "Stores the sealed session after the owner signed in through connect attempt `attempt`, which must belong to the session, be open, be held by this worker id and be before its deadline (409 `attempt_not_open` otherwise). The session becomes `active`, the attempt `succeeded`.",
                "operationId": "v1InternalStoreBrowserSessionState",
                "parameters": [
                    {
                        "name": "session",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "attempt",
                                    "sealed_state",
                                    "user_agent"
                                ],
                                "properties": {
                                    "attempt": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "sealed_state": {
                                        "description": "Opaque sealed session (secret; never logged).",
                                        "type": "string",
                                        "maxLength": 524288
                                    },
                                    "user_agent": {
                                        "type": "string"
                                    },
                                    "proxy_session": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "account_label": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "expires_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Stored",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "required": [
                                                "uuid",
                                                "status"
                                            ],
                                            "properties": {
                                                "uuid": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "pending_connect",
                                                        "active",
                                                        "expired",
                                                        "revoked"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ]
            }
        },
        "/v1/companies/{company}/agency/requests/{request}/accept": {
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Accept an agency's request",
                "description": "Scope: `companies:write`; the business's admins. The business joins the agency.",
                "operationId": "v1AcceptAgencyRequest",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CompanyAgency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/companies/{company}/agency/requests/{request}/decline": {
            "post": {
                "tags": [
                    "v1 agencies"
                ],
                "summary": "Decline an agency's request",
                "description": "Scope: `companies:write`; the business's admins.",
                "operationId": "v1DeclineAgencyRequest",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1CompanyAgency"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/directory/attribute-rankings": {
            "get": {
                "tags": [
                    "v1 directory"
                ],
                "summary": "Directory attribute top lists",
                "description": "Scope: `directory:read`. Attribute top lists of a category in a place for a season: per attribute the best shrunk scores of the businesses on grades.com with 5+ reviews that mention it (the pool), the pool size and the badge winner (`awarded`; not always #1, awards go where a business stands out most, at most 3 per business). Place = `metro`, `city` + `state`, `state`, or none for the whole directory. `season` = a key like `2026-fall` (default: the current season). 404 `unknown_category` / `unknown_place` / `unknown_attribute`. Super admins only during staging.",
                "operationId": "v1DirectoryAttributeRankings",
                "parameters": [
                    {
                        "name": "category",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "attribute",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 40
                        }
                    },
                    {
                        "name": "metro",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "city",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "state",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 2,
                            "minLength": 2
                        }
                    },
                    {
                        "name": "season",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 12
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 10,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` with `lists[]`; `meta` source, staging, disclosure.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "season": {
                                                    "type": "string",
                                                    "example": "2026-fall"
                                                },
                                                "season_name": {
                                                    "type": "string"
                                                },
                                                "category": {
                                                    "$ref": "#/components/schemas/V1DirectoryCategory"
                                                },
                                                "tier": {
                                                    "type": "string",
                                                    "enum": [
                                                        "city",
                                                        "metro",
                                                        "state",
                                                        "national"
                                                    ]
                                                },
                                                "place": {
                                                    "type": "string"
                                                },
                                                "min_pool": {
                                                    "type": "integer"
                                                },
                                                "note": {
                                                    "type": "string"
                                                },
                                                "lists": {
                                                    "type": "array",
                                                    "items": {
                                                        "properties": {
                                                            "attribute": {
                                                                "type": "string"
                                                            },
                                                            "label": {
                                                                "type": "string"
                                                            },
                                                            "place": {
                                                                "type": "string"
                                                            },
                                                            "pool_size": {
                                                                "type": "integer"
                                                            },
                                                            "winner_listing_id": {
                                                                "type": "integer",
                                                                "nullable": true
                                                            },
                                                            "winner_award_kind": {
                                                                "type": "string",
                                                                "nullable": true
                                                            },
                                                            "items": {
                                                                "type": "array",
                                                                "items": {
                                                                    "properties": {
                                                                        "rank": {
                                                                            "type": "integer"
                                                                        },
                                                                        "listing_id": {
                                                                            "type": "integer"
                                                                        },
                                                                        "name": {
                                                                            "type": "string"
                                                                        },
                                                                        "profile_url": {
                                                                            "type": "string",
                                                                            "format": "url",
                                                                            "nullable": true
                                                                        },
                                                                        "n": {
                                                                            "type": "integer"
                                                                        },
                                                                        "net": {
                                                                            "type": "number"
                                                                        },
                                                                        "shrunk": {
                                                                            "type": "number"
                                                                        },
                                                                        "awarded": {
                                                                            "type": "boolean"
                                                                        }
                                                                    },
                                                                    "type": "object"
                                                                }
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1DirectoryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "directory:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "directory:read"
                ]
            }
        },
        "/v1/directory/search": {
            "get": {
                "tags": [
                    "v1 directory"
                ],
                "summary": "Search the directory",
                "description": "Scope: `directory:read`. Listed businesses: `q` matches name, city, ZIP or category words; `near` (a ZIP, a state code or \"City, ST\") or `city` + `state` narrow the place; `category` (slug or name) the category. At least one of them. Name matches first. Super admins only during staging. Session twin `GET /api/directory/search` (dashboard, throttle `directory-search`). Own directory data only: no paid lookup.",
                "operationId": "v1DirectorySearch",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "near",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "city",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "state",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 2,
                            "minLength": 2
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 20,
                            "maximum": 50,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 1,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data[]` search cards; `meta` the directory meta plus total, page, limit, near.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1DirectorySearchResult"
                                            }
                                        },
                                        "meta": {
                                            "allOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1DirectoryMeta"
                                                },
                                                {
                                                    "properties": {
                                                        "total": {
                                                            "type": "integer"
                                                        },
                                                        "page": {
                                                            "type": "integer"
                                                        },
                                                        "limit": {
                                                            "type": "integer"
                                                        },
                                                        "near": {
                                                            "description": "The place `q`/`near` resolved to, if any.",
                                                            "type": "string",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            ]
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "directory:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "directory:read"
                ]
            }
        },
        "/v1/directory/rankings": {
            "get": {
                "tags": [
                    "v1 directory"
                ],
                "summary": "Directory ranking of a category in a place",
                "description": "Scope: `directory:read`. The ranking of a category in a place: the published monthly best-of ranking (`published: true`) when there is one, else the order of the businesses that meet every entry requirement as of today (`preview: true`; not a published ranking). Place = `metro` (slug or name), `city` + `state`, `state`, or `city` alone (looked up as a metro by name). `counts` (listed, eligible, brands) and `bar` (the published minimums and whether they are met). 404 `unknown_category` / `unknown_place`. Super admins only during staging.",
                "operationId": "v1DirectoryRankings",
                "parameters": [
                    {
                        "name": "category",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "metro",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "city",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 100
                        }
                    },
                    {
                        "name": "state",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "maxLength": 2,
                            "minLength": 2
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 10,
                            "maximum": 10,
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK: `data` the ranking with `items`; `meta` source, staging, disclosure.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1DirectoryRanking"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1DirectoryMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "directory:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "directory:read"
                ]
            }
        },
        "/v1/companies/{company}/reviews/export": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Export reviews (alias)",
                "description": "Scope: `reviews:read`. The same file as `GET .../exports/reviews.csv` (`format=csv`, the default) or `GET .../exports/reviews.xlsx` (`format=xlsx`).",
                "operationId": "v1ExportReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "csv",
                            "enum": [
                                "csv",
                                "xlsx"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "CSV file (`format=csv`) or Excel workbook (`format=xlsx`)",
                        "content": {
                            "text/csv": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/feedback": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List my reports",
                "description": "Needs no scope. The caller's own reports, newest first, with status and answer. `status` filters, `limit` (1-100, default 20) and `cursor` page.",
                "operationId": "v1ListFeedback",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1FeedbackReport"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Report a problem or give feedback",
                "description": "Needs no scope. Files a feedback or bug report for the caller; a confirmation e-mail with the reference goes to the caller's address. `origin` defaults to `mcp` for MCP access tokens and `api` for API keys (`assistant` for the dashboard assistant). `company` (uuid) must be a company the caller can use. 429 after 10 reports an hour.",
                "operationId": "v1CreateFeedback",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "kind",
                                    "summary"
                                ],
                                "properties": {
                                    "kind": {
                                        "type": "string",
                                        "enum": [
                                            "bug",
                                            "wrong_answer",
                                            "missing_feature",
                                            "question",
                                            "other"
                                        ]
                                    },
                                    "summary": {
                                        "type": "string",
                                        "maxLength": 200
                                    },
                                    "details": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 5000
                                    },
                                    "company": {
                                        "type": "string",
                                        "format": "uuid",
                                        "nullable": true
                                    },
                                    "origin": {
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "mcp",
                                            "assistant",
                                            "api"
                                        ]
                                    },
                                    "context": {
                                        "description": "What the caller was doing: `tool`, `expected`, `client`, `client_version`, `tool_call_id`, `session`, `conversation`, `page_url`, `app_version`, `request_id`.",
                                        "type": "object",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Filed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1FeedbackReport"
                                        },
                                        "meta": {
                                            "properties": {
                                                "confirmation_sent": {
                                                    "type": "boolean"
                                                },
                                                "confirmation_to": {
                                                    "type": "string",
                                                    "example": "j***@example.com",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            }
        },
        "/v1/feedback/{reference}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Get my report",
                "description": "Needs no scope. One of the caller's own reports by its reference (404 for anyone else's).",
                "operationId": "v1GetFeedback",
                "parameters": [
                    {
                        "name": "reference",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1FeedbackReport"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            }
        },
        "/v1/hub/companies": {
            "post": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Provision a location",
                "description": "Ability: `hub:provision`. Creates a Hub location (`source: hub`): the service user becomes its hidden super admin, the 3-month trial starts (the Hub promotion code with Stripe configured, else `trial_ends_at` = now + 90 days), and `owner` (optional) is invited as admin. Idempotent on (`hub_client_id`, `hub_location_key`): an existing location answers 200 unchanged (an offboarded one is reactivated).",
                "operationId": "v1HubProvisionCompany",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "hub_client_id",
                                    "hub_location_key",
                                    "name"
                                ],
                                "properties": {
                                    "hub_client_id": {
                                        "type": "string",
                                        "example": "4950",
                                        "maxLength": 32
                                    },
                                    "hub_location_key": {
                                        "type": "string",
                                        "example": "main",
                                        "maxLength": 64
                                    },
                                    "name": {
                                        "type": "string",
                                        "maxLength": 255
                                    },
                                    "location_nickname": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "website": {
                                        "type": "string",
                                        "format": "url",
                                        "nullable": true
                                    },
                                    "phone": {
                                        "description": "US number.",
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "email": {
                                        "type": "string",
                                        "format": "email",
                                        "nullable": true
                                    },
                                    "timezone": {
                                        "type": "string",
                                        "example": "America/New_York",
                                        "nullable": true
                                    },
                                    "address": {
                                        "properties": {
                                            "line1": {
                                                "type": "string"
                                            },
                                            "line2": {
                                                "type": "string"
                                            },
                                            "unit": {
                                                "type": "string"
                                            },
                                            "city": {
                                                "type": "string"
                                            },
                                            "state": {
                                                "type": "string"
                                            },
                                            "country": {
                                                "type": "string"
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    },
                                    "owner": {
                                        "properties": {
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            },
                                            "name": {
                                                "type": "string"
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    },
                                    "ai": {
                                        "description": "Seeds the AI reply settings (from the Hub Brand Profile).",
                                        "properties": {
                                            "business_description": {
                                                "type": "string"
                                            },
                                            "industry": {
                                                "type": "string"
                                            },
                                            "tone": {
                                                "type": "string"
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created. `meta`: `created`, `trial` (`promo` | `trial`), `owner` {email, invitation: `sent` | `existing_user_pending` | `already_member`}.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1HubLocation"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Already provisioned (`meta.created: false`; same `meta` keys as 201).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1HubLocation"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:provision"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "List the locations of a Hub client",
                "description": "Ability: `hub:read`. Every location of a Hub client with status, plan, sources (sync health), counts and portal users.",
                "operationId": "v1HubClientLocations",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1HubLocation"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:read"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}/{locationKey}": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Get a Hub location",
                "description": "Ability: `hub:read`. One location.",
                "operationId": "v1HubLocation",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1HubLocation"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:read"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}/{locationKey}/offboard": {
            "post": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Offboard a location",
                "description": "Ability: `hub:provision`. Deactivates the location: the review agent is switched off, sources stop syncing, publishable keys and webhooks are revoked, and members who have no other active location lose their API keys. Data is kept for 30 days (`meta.purge_after`), then `hub:purge-offboarded` deletes it. Provisioning the same ids again reactivates it. Idempotent.",
                "operationId": "v1HubOffboard",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Offboarded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1HubLocation"
                                        },
                                        "meta": {
                                            "properties": {
                                                "purge_after": {
                                                    "description": "When `hub:purge-offboarded` may delete the data.",
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:provision"
                ]
            }
        },
        "/v1/hub/directory/locations": {
            "put": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Push directory locations",
                "description": "Ability: `hub:directory`. Upserts Hub locations (send at most 50 per call; up to 200 are accepted) as managed directory listings; company link-up, review sources and geocoding follow on the worker. Idempotent on (`hub_client_id`, `hub_location_key`): the same payload again is `unchanged` and writes nothing, an older `source_updated_at` is `stale`. `directory: false` opts a location out (not created, or hidden), `active_seo: false` (not an active SEO client) likewise; excluded businesses are refused per item (`excluded`), restricted niches are stored hidden. Name, address and phone disagreements with other sources are queued for review (`conflicts`). Contract: docs/hub-directory-contract.md.",
                "operationId": "v1HubDirectoryPutLocations",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "locations"
                                ],
                                "properties": {
                                    "locations": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "maxItems": 200
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Per-item results (`status`: created, updated, unchanged, stale, skipped, excluded) and counts in `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "hub_client_id": {
                                                        "type": "string"
                                                    },
                                                    "hub_location_key": {
                                                        "type": "string"
                                                    },
                                                    "status": {
                                                        "type": "string",
                                                        "enum": [
                                                            "created",
                                                            "updated",
                                                            "unchanged",
                                                            "stale",
                                                            "skipped",
                                                            "excluded"
                                                        ]
                                                    },
                                                    "listing_id": {
                                                        "type": "integer",
                                                        "nullable": true
                                                    },
                                                    "hidden_reason": {
                                                        "type": "string",
                                                        "nullable": true
                                                    },
                                                    "changed": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "conflicts": {
                                                        "description": "Name, address and phone disagreements queued for review.",
                                                        "type": "integer"
                                                    },
                                                    "warnings": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "sources": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1HubDirectoryPushMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:directory"
                ]
            }
        },
        "/v1/hub/directory/brands": {
            "put": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Push directory brands",
                "description": "Ability: `hub:directory`. Upserts up to 200 national and e-commerce Brand Profiles keyed by `hub_client_id` (name, website, `industry` = \"Industry > Subindustry\", short and long description, logo URL on the client's own site, review-site URLs). Same idempotency and listing rules as locations.",
                "operationId": "v1HubDirectoryPutBrands",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "brands"
                                ],
                                "properties": {
                                    "brands": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "maxItems": 200
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Per-item results and counts in `meta`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "hub_client_id": {
                                                        "type": "string"
                                                    },
                                                    "status": {
                                                        "type": "string",
                                                        "enum": [
                                                            "created",
                                                            "updated",
                                                            "unchanged",
                                                            "stale",
                                                            "skipped",
                                                            "excluded"
                                                        ]
                                                    },
                                                    "brand_id": {
                                                        "type": "integer",
                                                        "nullable": true
                                                    },
                                                    "hidden_reason": {
                                                        "type": "string",
                                                        "nullable": true
                                                    },
                                                    "changed": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "warnings": {
                                                        "type": "array",
                                                        "items": {
                                                            "type": "string"
                                                        }
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1HubDirectoryPushMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:directory"
                ]
            }
        },
        "/v1/hub/directory/locations/{hubClientId}/{locationKey}": {
            "delete": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Stop managing a directory location",
                "description": "Ability: `hub:directory`. The location is no longer managed by the Hub (`claim_state: unclaimed`); the listing, its public id and URL stay. Never deletes. Idempotent.",
                "operationId": "v1HubDirectoryUnmanageLocation",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The listing, unmanaged.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1HubDirectoryListing"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:directory"
                ]
            }
        },
        "/v1/hub/directory/locations/{hubClientId}": {
            "get": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "List the directory listings of a Hub client",
                "description": "Ability: `hub:directory`. The directory listings of a Hub client: state, profile URL, the grade badge (SVG URL + embed snippet; `available` once the listing is published with a final grade) and the facts grades.com stores (address, phone, website, hours, categories...), with the source each published value comes from (`provenance`) and the open name / address / phone `conflicts`. `meta.brand`: the client's brand profile with its stored facts, if any. Contract: docs/hub-directory-contract.md \"Reading back\".",
                "operationId": "v1HubDirectoryClientLocations",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1HubDirectoryListingFacts"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "hub_client_id": {
                                                    "type": "string"
                                                },
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "brand": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/V1HubDirectoryBrand"
                                                        },
                                                        {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "enum": [
                                                                null
                                                            ]
                                                        }
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:directory"
                ]
            }
        },
        "/v1/hub/directory/locations/{hubClientId}/{locationKey}/reviews:ingest": {
            "post": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Push Google reviews of a directory listing",
                "description": "Ability: `hub:ingest` or `hub:directory`. The Google reviews of a directory listing the Hub syncs through the Business Profile API, for listings whose client was never provisioned with `POST /v1/hub/companies`. Stored on the listing's company (an unclaimed directory company or an adopted tenant; in its Business Profile source when it has one, else an `api` source), idempotent on `review_id`; at most 500 per call, zero with `google_stats` alone. `removed_at` removes a stored review (restored when sent again without it). A tenant hears only of reviews published after the location's first ingest. The company's paid Google Maps source is not parsed while pushes keep coming. 404 `listing_not_found` before the directory push listed the location; 409 `listing_unlinked` while the listing has no company. Contract: docs/hub-directory-contract.md.",
                "operationId": "v1HubDirectoryIngestReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "reviews": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "review_id"
                                            ],
                                            "properties": {
                                                "source": {
                                                    "type": "string",
                                                    "enum": [
                                                        "google"
                                                    ]
                                                },
                                                "review_id": {
                                                    "type": "string",
                                                    "maxLength": 191
                                                },
                                                "rating": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "maximum": 5,
                                                    "minimum": 1
                                                },
                                                "text": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "author_name": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "created_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "updated_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "reply": {
                                                    "properties": {
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "replied_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "removed_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "maxItems": 500
                                    },
                                    "google_stats": {
                                        "properties": {
                                            "rating": {
                                                "type": "number",
                                                "nullable": true
                                            },
                                            "review_count": {
                                                "type": "integer",
                                                "nullable": true
                                            },
                                            "observed_at": {
                                                "type": "string",
                                                "format": "date-time",
                                                "nullable": true
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    },
                                    "industry": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Counts (`created`, `updated`, `unchanged`, `removed`); `meta.google_stats`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "created": {
                                                    "type": "integer"
                                                },
                                                "updated": {
                                                    "type": "integer"
                                                },
                                                "unchanged": {
                                                    "type": "integer"
                                                },
                                                "removed": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "received": {
                                                    "type": "integer"
                                                },
                                                "google_stats": {
                                                    "description": "`stored` when `google_stats` was recorded, else null.",
                                                    "type": "string",
                                                    "nullable": true,
                                                    "enum": [
                                                        "stored"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:ingest",
                    "hub:directory"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}/{locationKey}/sources": {
            "post": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Connect a review source to a Hub location",
                "description": "Ability: `hub:provision`. Same body and validation as `POST /v1/companies/{company}/sources` (URL drivers, verified Apify drivers, `g2`). Google and Facebook need the owner's OAuth consent: 422 `oauth_required`, sign the owner in with a login link instead. Google reviews of Hub clients are pushed with `reviews:ingest`.",
                "operationId": "v1HubConnectSource",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "driver"
                                ],
                                "properties": {
                                    "driver": {
                                        "type": "string",
                                        "example": "yelp"
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "url"
                                    },
                                    "token": {
                                        "type": "string"
                                    },
                                    "product_name": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created (a `V1Source`)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Source"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:provision"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}/{locationKey}/reviews:ingest": {
            "post": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Push Google reviews",
                "description": "Ability: `hub:ingest`. Pushes Google reviews into the location's `api` source. Upsert by `system_id` (the GBP review id); at most 500 per call; `system_id`s must be distinct. Edits keep a history and update statistics like parsed reviews; pushes never emit webhooks. `removed_at` removes a stored review (restored when pushed again without it); `reply` is the owner response. `google_stats` (rating, review count) is stored for the directory score. The location's paid Google source is not parsed while pushes keep coming. 409 `offboarded`; 402 `billing_locked` once a locked location is no longer refreshed.",
                "operationId": "v1HubIngestReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "reviews"
                                ],
                                "properties": {
                                    "reviews": {
                                        "type": "array",
                                        "items": {
                                            "required": [
                                                "system_id"
                                            ],
                                            "properties": {
                                                "system_id": {
                                                    "type": "string",
                                                    "maxLength": 191
                                                },
                                                "rating": {
                                                    "type": "integer",
                                                    "nullable": true,
                                                    "maximum": 5,
                                                    "minimum": 1
                                                },
                                                "text": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "username": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "avatar": {
                                                    "type": "string",
                                                    "format": "url",
                                                    "nullable": true
                                                },
                                                "published_date": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "external_url": {
                                                    "type": "string",
                                                    "format": "url",
                                                    "nullable": true
                                                },
                                                "response_text": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "response_date": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                },
                                                "reply": {
                                                    "properties": {
                                                        "text": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "replied_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        }
                                                    },
                                                    "type": "object",
                                                    "nullable": true
                                                },
                                                "removed_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "maxItems": 500,
                                        "minItems": 1
                                    },
                                    "google_stats": {
                                        "properties": {
                                            "rating": {
                                                "type": "number",
                                                "nullable": true
                                            },
                                            "review_count": {
                                                "type": "integer",
                                                "nullable": true
                                            },
                                            "observed_at": {
                                                "type": "string",
                                                "format": "date-time",
                                                "nullable": true
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Counts",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "created": {
                                                    "type": "integer"
                                                },
                                                "updated": {
                                                    "type": "integer"
                                                },
                                                "unchanged": {
                                                    "type": "integer"
                                                },
                                                "removed": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/BillingProblem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:ingest"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}/{locationKey}/users": {
            "post": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Invite a portal user",
                "description": "Ability: `hub:provision`. Invites a portal user (default role `admin`) through the normal invitation email. An email without a Grades account gets one; an existing account gets a pending invitation it must accept (`existing_user_pending`). Already a member: 200 `already_member`.",
                "operationId": "v1HubInviteUser",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "name": {
                                        "type": "string"
                                    },
                                    "role": {
                                        "type": "string",
                                        "default": "admin",
                                        "enum": [
                                            "admin",
                                            "user"
                                        ]
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Invited: `{email, role, invitation: sent | existing_user_pending}`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1HubInvitation"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Already a member (`invitation: already_member`)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1HubInvitation"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:provision"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}/{locationKey}/users/{email}": {
            "delete": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Remove a portal user",
                "description": "Ability: `hub:provision`. Removes a member (or a pending invitation). The user account itself is kept.",
                "operationId": "v1HubRemoveUser",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    },
                    {
                        "name": "email",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Removed"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:provision"
                ]
            }
        },
        "/v1/hub/companies/{hubClientId}/{locationKey}/login-link": {
            "post": {
                "tags": [
                    "v1 hub"
                ],
                "summary": "Mint a login link",
                "description": "Ability: `hub:provision`. A one-time sign-in URL for an accepted member of the location: valid 60 seconds (`HUB_SSO_TTL_SECONDS`), single use, HMAC-signed and bound to that user and location. Opening it signs the user in to Grades, selects the location and redirects to the dashboard. 404 `user_not_member`, 409 `invitation_pending` or `offboarded`. Redirect the browser at once; never store or log the URL.",
                "operationId": "v1HubLoginLink",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/HubClientId"
                    },
                    {
                        "$ref": "#/components/parameters/HubLocationKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "url": {
                                                    "type": "string",
                                                    "format": "url"
                                                },
                                                "expires_at": {
                                                    "type": "string",
                                                    "format": "date-time"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "x-hub-abilities": [
                    "hub:provision"
                ]
            }
        },
        "/v1/companies/{company}/integrations/hubspot/pipelines": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "HubSpot pipelines and stages",
                "description": "Scope: `companies:read`, company admins. The connected HubSpot account's deal pipelines (each stage with `won`) and ticket pipelines (each stage with `closed`; empty without the tickets permission), read live from HubSpot. Pick stage ids for `settings.hubspot.deal_stages` / `ticket_stages`. `meta.tickets_permission`: false when HubSpot refused the ticket scope (`meta.tickets_permission_fix` says where the HubSpot admin turns it on).",
                "operationId": "v1HubSpotPipelines",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "deals": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object"
                                                    }
                                                },
                                                "tickets": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/webhooks": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List webhook endpoints",
                "description": "Scope: `reviews:read`. The caller's endpoints (without secrets). A key or connection limited to some businesses sees only endpoints of those businesses (no account-wide ones).",
                "operationId": "v1ListWebhooks",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1WebhookEndpoint"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Create a webhook endpoint",
                "description": "Scope: `reviews:write`. Registers an https endpoint for the events in `events` (list: `GET /v1/webhooks/events`; all by default). With `company` the endpoint gets that company's events; without it (Hub service key only) every location of the account. A key or connection limited to some businesses must name one of them (400 `company_required` without `company`, 404 for a business outside its list). Deliveries are signed: `X-Grades-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<body>\")>`. The `secret` is returned only here (201). Idempotent per owner, company and URL: when the caller already has an active endpoint for the same company and exactly this URL, the answer is `200` with that endpoint and `meta.existing: true` (same events; no `secret`) or `409` `code: endpoint_exists` with `endpoint_id` (other events: delete it first). The URL must be https on a public host and must not contain a user name or password.",
                "operationId": "v1CreateWebhook",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "url"
                                ],
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "format": "url"
                                    },
                                    "events": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "enum": [
                                                "review.created",
                                                "review.updated",
                                                "review.removed",
                                                "review.replied",
                                                "agent.action.pending",
                                                "agent.action.posted",
                                                "source.reconnect_required",
                                                "radar.mention.found",
                                                "radar.ai_perception.changed",
                                                "review_request.clicked",
                                                "review_request.visited",
                                                "review_request.reviewed",
                                                "review_request.unsubscribed",
                                                "recovery.case.opened",
                                                "review.tagged"
                                            ]
                                        }
                                    },
                                    "company": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "description": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created. `Location`: the URL of the endpoint (`/api/v1/webhooks/{id}`; DELETE it to unsubscribe).",
                        "headers": {
                            "Location": {
                                "description": "The resource URL of the endpoint",
                                "schema": {
                                    "type": "string",
                                    "format": "uri"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WebhookEndpointCreated"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "The caller already has this subscription (same company, URL and events); no secret. `Location`: the URL of the endpoint.",
                        "headers": {
                            "Location": {
                                "description": "The resource URL of the endpoint",
                                "schema": {
                                    "type": "string",
                                    "format": "uri"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WebhookEndpoint"
                                        },
                                        "meta": {
                                            "properties": {
                                                "existing": {
                                                    "type": "boolean",
                                                    "example": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/webhooks/events": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List webhook events",
                "description": "Scope: `reviews:read`. Every webhook event with a one-line description and an example `data` (the body of a delivery is `{id, type, created_at, company, data}`). For integration builders (Zapier, Make, n8n): docs/integrations.md.",
                "operationId": "v1ListWebhookEvents",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "properties": {
                                                    "type": {
                                                        "type": "string",
                                                        "enum": [
                                                            "review.created",
                                                            "review.updated",
                                                            "review.removed",
                                                            "review.replied",
                                                            "agent.action.pending",
                                                            "agent.action.posted",
                                                            "source.reconnect_required",
                                                            "radar.mention.found",
                                                            "radar.ai_perception.changed",
                                                            "review_request.clicked",
                                                            "review_request.visited",
                                                            "review_request.reviewed",
                                                            "review_request.unsubscribed",
                                                            "recovery.case.opened",
                                                            "review.tagged"
                                                        ]
                                                    },
                                                    "description": {
                                                        "type": "string"
                                                    },
                                                    "example": {
                                                        "type": "object"
                                                    }
                                                },
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/webhooks/samples": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Sample webhook bodies",
                "description": "Scope: `reviews:read`. Up to 3 bodies of one event for a company, newest first, in exactly the shape a delivery has (Zapier `performList`, Make and n8n samples): bodies already delivered for the company, else built from its latest matching records, else the example. Each body has `sample`: `delivered`, `recent` or `example`. Nothing is sent.",
                "operationId": "v1WebhookSamples",
                "parameters": [
                    {
                        "name": "event",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "review.created",
                                "review.updated",
                                "review.removed",
                                "review.replied",
                                "agent.action.pending",
                                "agent.action.posted",
                                "source.reconnect_required",
                                "radar.mention.found",
                                "radar.ai_perception.changed",
                                "review_request.clicked",
                                "review_request.visited",
                                "review_request.reviewed",
                                "review_request.unsubscribed",
                                "recovery.case.opened",
                                "review.tagged"
                            ]
                        }
                    },
                    {
                        "name": "company",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/webhooks/{webhook}": {
            "delete": {
                "tags": [
                    "v1"
                ],
                "summary": "Delete a webhook endpoint",
                "description": "Scope: `reviews:read`. Deletes one of the caller's endpoints and its delivery log. A key or connection limited to some businesses deletes only endpoints of those businesses (404 otherwise).",
                "operationId": "v1DeleteWebhook",
                "parameters": [
                    {
                        "name": "webhook",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Deleted"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/companies/{company}/locations/stats": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Multi-location rollup and comparison",
                "description": "Scope: `reviews:read`. Rollup of the HQ and its locations for a period (`from`/`to`, dates in the HQ's timezone, inclusive; default the last 30 days) against the previous period of the same length: `totals`, one row per location (`locations`, sorted by `sort`/`order` with `rank`) and one per review source driver (`sources`, internal ids) and one per review platform (`platforms`: `platform`, display `name`, `sources`; the drivers of one platform merged, what to show people). `location` (uuids, comma-separated) and `source` (drivers) narrow it.",
                "operationId": "v1LocationStats",
                "parameters": [
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "location",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "source",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "default": "name",
                            "enum": [
                                "name",
                                "reviews_total",
                                "rating_average",
                                "new_reviews",
                                "new_rating_average",
                                "response_rate",
                                "unanswered_negative",
                                "pending_agent_actions",
                                "low_ratings",
                                "unanswered"
                            ]
                        }
                    },
                    {
                        "name": "order",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "asc",
                                "desc"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1LocationStats"
                                        },
                                        "meta": {
                                            "required": [
                                                "from",
                                                "to",
                                                "previous_from",
                                                "previous_to",
                                                "timezone",
                                                "sort",
                                                "locations_count",
                                                "hq"
                                            ],
                                            "properties": {
                                                "from": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "to": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "previous_from": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "previous_to": {
                                                    "type": "string",
                                                    "format": "date"
                                                },
                                                "timezone": {
                                                    "type": "string"
                                                },
                                                "sort": {
                                                    "type": "string"
                                                },
                                                "locations_count": {
                                                    "type": "integer"
                                                },
                                                "hq": {
                                                    "$ref": "#/components/schemas/V1LocationHq"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/companies/{company}/locations/reviews": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Reviews of all locations",
                "description": "Scope: `reviews:read`. One review feed for the HQ and its locations: the filters, sorts and cursor pagination of `GET /v1/companies/{company}/reviews`, plus `location` (uuids, comma-separated). Each review carries its `location`.",
                "operationId": "v1LocationReviews",
                "parameters": [
                    {
                        "name": "location",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "allOf": [
                                                    {
                                                        "$ref": "#/components/schemas/V1Review"
                                                    },
                                                    {
                                                        "required": [
                                                            "location"
                                                        ],
                                                        "properties": {
                                                            "location": {
                                                                "nullable": true,
                                                                "allOf": [
                                                                    {
                                                                        "$ref": "#/components/schemas/V1LocationRef"
                                                                    }
                                                                ]
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                ]
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "limit",
                                                "sort",
                                                "next_cursor",
                                                "has_more"
                                            ],
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "sort": {
                                                    "type": "string"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                },
                                                "total": {
                                                    "description": "Only with `include_total_quantity=true`.",
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/companies/{company}/locations/agent/actions": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Agent actions of all locations",
                "description": "Scope: `reviews:read`. The review agent's queue and history across the HQ and its locations, newest first, with each action's `location`. Approve or reject through `POST /v1/companies/{location.uuid}/agent/actions/{uuid}/approve|reject`. `meta.pending_count` counts pending actions of the selected locations, `meta.pending_by_location` per location uuid. `assigned=me`: only the locations whose approval notices go to the caller (`meta.assigned_to_me` lists their uuids; www/docs/roles.md section 7).",
                "operationId": "v1LocationAgentActions",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pending",
                                "approved",
                                "rejected",
                                "executed",
                                "failed",
                                "expired",
                                "skipped"
                            ]
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "reply",
                                "flag"
                            ]
                        }
                    },
                    {
                        "name": "location",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "assigned",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "me"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 25,
                            "maximum": 100,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "allOf": [
                                                    {
                                                        "$ref": "#/components/schemas/V1AgentAction"
                                                    },
                                                    {
                                                        "required": [
                                                            "location"
                                                        ],
                                                        "properties": {
                                                            "location": {
                                                                "nullable": true,
                                                                "allOf": [
                                                                    {
                                                                        "$ref": "#/components/schemas/V1LocationRef"
                                                                    }
                                                                ]
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                ]
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "limit",
                                                "next_cursor",
                                                "has_more",
                                                "total",
                                                "pending_count",
                                                "pending_by_location",
                                                "assigned_to_me"
                                            ],
                                            "properties": {
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                },
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "pending_count": {
                                                    "type": "integer"
                                                },
                                                "pending_by_location": {
                                                    "description": "Pending actions per location uuid.",
                                                    "type": "object",
                                                    "additionalProperties": {
                                                        "type": "integer"
                                                    }
                                                },
                                                "assigned_to_me": {
                                                    "description": "Uuids of the locations whose approval notices go to the caller.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string",
                                                        "format": "uuid"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/companies/{company}/locations/settings": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Settings of all locations",
                "description": "Scope: `companies:read`. Each location's review agent settings and default review page side by side (`review_page` is null until the location has one), with the HQ's values in `meta.hq` so clients can show which locations differ.",
                "operationId": "v1LocationSettings",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1LocationSettingsRow"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count",
                                                "hq",
                                                "page_fields"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "hq": {
                                                    "description": "The HQ's row (the first of `data`).",
                                                    "nullable": true,
                                                    "allOf": [
                                                        {
                                                            "$ref": "#/components/schemas/V1LocationSettingsRow"
                                                        }
                                                    ]
                                                },
                                                "page_fields": {
                                                    "description": "The review page fields that can be copied.",
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Apply settings to locations",
                "description": "Scope: `reviews:write` (plus `companies:write` with `review_page`); admins of the HQ. Copies the fields sent in `agent` (review agent settings, as in `PUT .../agent/settings`) and `review_page` (`enabled`, `headline`, `intro`, `closing`, `accent_color`, `theme`, `show_logo`, `show_feedback_form`, `feedback_email` of the default page) to `locations` (uuids, or `\"all\"`). Each location keeps editing its own values afterwards. Each location is applied on its own: `data[].status` is `applied` or `failed` (with `error.code`, e.g. `billing_locked`, `plan_upgrade_required`); nothing of a failed location changes.",
                "operationId": "v1ApplyLocationSettings",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "locations"
                                ],
                                "properties": {
                                    "locations": {
                                        "description": "Location uuids (the HQ included if wanted), or \"all\".",
                                        "oneOf": [
                                            {
                                                "type": "array",
                                                "items": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                }
                                            },
                                            {
                                                "type": "string",
                                                "enum": [
                                                    "all"
                                                ]
                                            }
                                        ]
                                    },
                                    "agent": {
                                        "type": "object"
                                    },
                                    "review_page": {
                                        "type": "object"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1LocationSettingsResult"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count",
                                                "applied",
                                                "failed"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "applied": {
                                                    "type": "integer"
                                                },
                                                "failed": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            }
        },
        "/v1/companies/{company}/locations/members": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Members of an HQ and their location access",
                "description": "Scope: `companies:read`. Members of the HQ with `all_locations` (their membership covers every location) and the locations they are also a member of directly.",
                "operationId": "v1LocationMembers",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1LocationMember"
                                            }
                                        },
                                        "meta": {
                                            "required": [
                                                "count"
                                            ],
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/companies/{company}/locations/members/{user}": {
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Change a member's location access",
                "description": "Scope: `companies:write`; admins of the HQ (only super admins change other super admins). `all_locations: true` lets this HQ member use every location with their HQ role; `false` limits them to the HQ company (and locations they are a direct member of). Takes effect at once.",
                "operationId": "v1UpdateLocationMember",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "all_locations"
                                ],
                                "properties": {
                                    "all_locations": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "required": [
                                        "data",
                                        "meta"
                                    ],
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1LocationMember"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/me": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Current user",
                "description": "Returns the user the credential belongs to, plus the credential type and scopes. Needs no particular scope; useful for checking a key.",
                "operationId": "v1GetMe",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "uuid": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "format": "email"
                                                },
                                                "is_superadmin": {
                                                    "description": "Platform super admin: a member of every company with the role `super_admin` (docs/api-v1.md, Super admin).",
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "meta": {
                                            "properties": {
                                                "credential": {
                                                    "properties": {
                                                        "type": {
                                                            "type": "string",
                                                            "enum": [
                                                                "api_key",
                                                                "oauth"
                                                            ]
                                                        },
                                                        "scopes": {
                                                            "type": "array",
                                                            "items": {
                                                                "type": "string"
                                                            }
                                                        }
                                                    },
                                                    "type": "object"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": []
                    }
                ]
            }
        },
        "/v1/public/reviews": {
            "get": {
                "tags": [
                    "v1 public"
                ],
                "summary": "Public reviews",
                "description": "Visible reviews of the key's company. Reviews from a source shown only as a rating and a link (Yelp) have null `text`, `author`, `avatar` and `response_text` and `text_policy: aggregate`. Cacheable for `API_PUBLIC_CACHE_MAX_AGE` seconds (default 300) and conditional with `If-None-Match`. CORS-enabled; 600 requests/minute per key.",
                "operationId": "v1PublicReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReviewMinRating"
                    },
                    {
                        "$ref": "#/components/parameters/V1PublicSources"
                    },
                    {
                        "$ref": "#/components/parameters/V1PublicLimit"
                    },
                    {
                        "$ref": "#/components/parameters/V1PublicSort"
                    },
                    {
                        "$ref": "#/components/parameters/V1Cursor"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "allOf": [
                                                    {
                                                        "$ref": "#/components/schemas/V1PublicReview"
                                                    },
                                                    {
                                                        "required": [
                                                            "text_policy"
                                                        ],
                                                        "properties": {
                                                            "text_policy": {
                                                                "description": "`aggregate` when the review's source may only be shown as a rating and a link (Yelp): `text`, `author`, `avatar` and `response_text` are then null. Null for every other review.",
                                                                "type": "string",
                                                                "nullable": true,
                                                                "enum": [
                                                                    "aggregate"
                                                                ]
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                ]
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "company": {
                                                    "properties": {
                                                        "name": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "type": "object"
                                                },
                                                "limit": {
                                                    "type": "integer"
                                                },
                                                "sort": {
                                                    "type": "string",
                                                    "enum": [
                                                        "newest",
                                                        "best"
                                                    ]
                                                },
                                                "next_cursor": {
                                                    "type": "string",
                                                    "nullable": true
                                                },
                                                "has_more": {
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified (ETag matched)"
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "publishableKey": []
                    },
                    {
                        "publishableKeyHeader": []
                    }
                ]
            }
        },
        "/v1/public/summary": {
            "get": {
                "tags": [
                    "v1 public"
                ],
                "summary": "Public rating summary",
                "description": "The business's true overall rating and review count, overall and per review site, the same figures the review widgets show (the directory profile's totals over every rated review of the featured sites, published site totals where the score counted them; a review hidden from widgets still counts), plus a ready-made schema.org `AggregateRating` object for JSON-LD (null when nothing is rated). `sources` keys are public site keys (google, facebook, yelp, grades ...).",
                "operationId": "v1PublicSummary",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/V1PublicSources"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "name": {
                                                    "type": "string"
                                                },
                                                "average_rating": {
                                                    "type": "number",
                                                    "example": 4.7,
                                                    "nullable": true
                                                },
                                                "total": {
                                                    "description": "Rated reviews counted in the rating.",
                                                    "type": "integer"
                                                },
                                                "rated": {
                                                    "description": "The same as total (kept for older clients).",
                                                    "type": "integer"
                                                },
                                                "sources": {
                                                    "type": "object",
                                                    "additionalProperties": {
                                                        "properties": {
                                                            "name": {
                                                                "description": "The site as visitors know it (\"Google\").",
                                                                "type": "string"
                                                            },
                                                            "kind": {
                                                                "description": "site, grades or api (added by your own software, no review site).",
                                                                "type": "string"
                                                            },
                                                            "average_rating": {
                                                                "type": "number",
                                                                "nullable": true
                                                            },
                                                            "total": {
                                                                "type": "integer"
                                                            },
                                                            "rated": {
                                                                "type": "integer"
                                                            }
                                                        },
                                                        "type": "object"
                                                    }
                                                },
                                                "aggregate_rating": {
                                                    "description": "schema.org AggregateRating, ready for a JSON-LD script tag.",
                                                    "type": "object",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified (ETag matched)"
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "publishableKey": []
                    },
                    {
                        "publishableKeyHeader": []
                    }
                ]
            }
        },
        "/v1/public/showcase": {
            "get": {
                "tags": [
                    "v1 public"
                ],
                "summary": "Public Review Showcase",
                "description": "A selection of the key's company's own reviews by rules (see `/v1/companies/{company}/showcase`). `showcase` = a saved showcase of the same company. Cacheable for `SHOWCASE_HTTP_MAX_AGE` seconds (default 600); new reviews appear within the plan's refresh window (Starter 24 h, Pro 1 h, Premium 10 min). CORS-enabled; 600 requests/minute per key.",
                "operationId": "v1PublicShowcase",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ShowcaseCount"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMinRating"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMinLength"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMaxLength"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseTopic"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseSites"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseMaxAge"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseLanguage"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseSeed"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseStyle"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseInclude"
                    },
                    {
                        "$ref": "#/components/parameters/ShowcaseSaved"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (`format=json`; the other formats answer the raw document).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ShowcaseReview"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ShowcaseMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified (ETag matched)"
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "publishableKey": []
                    },
                    {
                        "publishableKeyHeader": []
                    }
                ]
            }
        },
        "/v1/public/widget": {
            "get": {
                "tags": [
                    "v1 public"
                ],
                "summary": "Public review widget",
                "description": "The data of a review widget of the key's company (`preset` pill, strip, carousel, grid, list, masonry, spotlight, summary, wall, video, badge, popup or tab; `theme`, `accent`, `lang`, `count`, `min_rating`, `sites` and the preset's display options; `showcase` = a saved showcase of the same company, its rules). Reviews follow the Review Showcase rules and never carry Yelp text. Cacheable for `SHOWCASE_HTTP_MAX_AGE` seconds. Display options (`show_grade`, `show_count`, `show_rating`, `rating_decimals`, `show_stars`, `show_rating_word`, `show_source_mark`, `label`) as for the company endpoint; a bad one is a 422. A claimed listing without a paid plan gets the pill and the strip with Google and Reviews on Grades.com only (else 402). `demo=1` without a key: the sample business of the www.grades.com widget pages (`demo: true`, noindex, 60 a minute per IP; CORS for grades.com pages only).",
                "operationId": "v1PublicWidget",
                "parameters": [
                    {
                        "name": "preset",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "pill",
                                "strip",
                                "carousel",
                                "grid",
                                "list",
                                "masonry",
                                "spotlight",
                                "summary",
                                "wall",
                                "video",
                                "badge",
                                "popup",
                                "tab",
                                "button"
                            ]
                        }
                    },
                    {
                        "name": "theme",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "light",
                                "dark",
                                "auto"
                            ]
                        }
                    },
                    {
                        "name": "accent",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "count",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 30,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "min_rating",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 5,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "sites",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "lang",
                        "in": "query",
                        "description": "Language of the widget's own words (the reviews are shown as written).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es"
                            ]
                        }
                    },
                    {
                        "name": "columns",
                        "in": "query",
                        "description": "grid, masonry, wall: most columns (2-4, default 3).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                2,
                                3,
                                4
                            ]
                        }
                    },
                    {
                        "name": "autoplay",
                        "in": "query",
                        "description": "carousel, spotlight: on|off (default on).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "interval",
                        "in": "query",
                        "description": "carousel, spotlight, popup: seconds per review (4-20; default 6, 8, 10).",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 20,
                            "minimum": 4
                        }
                    },
                    {
                        "name": "show_dates",
                        "in": "query",
                        "description": "on|off (default on).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_site",
                        "in": "query",
                        "description": "on|off: the review site's icon on each review (default on).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "position",
                        "in": "query",
                        "description": "badge, popup, tab: the side of the page (default right; popup left).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "left",
                                "right"
                            ]
                        }
                    },
                    {
                        "name": "mobile",
                        "in": "query",
                        "description": "popup: also on phones (default off).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "variant",
                        "in": "query",
                        "description": "pill: bordered|plain.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "bordered",
                                "plain"
                            ]
                        }
                    },
                    {
                        "name": "panel",
                        "in": "query",
                        "description": "pill: on|off.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_grade",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_count",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_rating",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "rating_decimals",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1,
                                2
                            ]
                        }
                    },
                    {
                        "name": "show_stars",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_rating_word",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "show_source_mark",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "label",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 40
                        }
                    },
                    {
                        "name": "show_summary",
                        "in": "query",
                        "description": "Widgets v2 (only while the gate admits the business, else ignored): the approved AI summary line.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "controls",
                        "in": "query",
                        "description": "Widgets v2: sites, stars, sort (comma list).",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "newest",
                                "highest",
                                "lowest"
                            ]
                        }
                    },
                    {
                        "name": "translate",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "on",
                                "off",
                                "1",
                                "0",
                                "true",
                                "false",
                                "yes",
                                "no"
                            ]
                        }
                    },
                    {
                        "name": "v_site",
                        "in": "query",
                        "description": "Widgets v2 visitor param: a site tab.",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "v_stars",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 5,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "v_sort",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "newest",
                                "highest",
                                "lowest"
                            ]
                        }
                    },
                    {
                        "name": "v_page",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 20,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "demo",
                        "in": "query",
                        "description": "1 = the demo widget of the sample business (no key needed; browsers read it from grades.com pages only).",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "1"
                            ]
                        }
                    },
                    {
                        "name": "showcase",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1WidgetData"
                                        },
                                        "meta": {
                                            "properties": {
                                                "options": {
                                                    "description": "The resolved options.",
                                                    "type": "object",
                                                    "additionalProperties": true
                                                },
                                                "embed": {
                                                    "$ref": "#/components/schemas/V1WidgetEmbed"
                                                },
                                                "demo": {
                                                    "description": "`demo=1` only: always true.",
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified (ETag matched)"
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "402": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "publishableKey": []
                    },
                    {
                        "publishableKeyHeader": []
                    }
                ]
            }
        },
        "/v1/reports": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List reports",
                "description": "Scope: `reviews:read`. The reports with their columns, parameters and URLs; `meta.limits`.",
                "operationId": "v1ListReports",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/reports/locations": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Report: locations",
                "description": "One row per business the key reaches (the dimension table). Scope: `reviews:read`. JSON `{data: [rows], meta}` or `format=csv`. Rows of every business the credential reaches, by business, then in a stable order; columns in `meta.columns`.",
                "operationId": "v1ReportLocations",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReportCompany"
                    },
                    {
                        "$ref": "#/components/parameters/ReportLimit"
                    },
                    {
                        "$ref": "#/components/parameters/ReportCursor"
                    },
                    {
                        "$ref": "#/components/parameters/ReportPage"
                    },
                    {
                        "$ref": "#/components/parameters/ReportFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ReportKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (JSON or CSV)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReportPageMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/reports/reviews": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Report: reviews",
                "description": "One row per review (dates on the publish date). `include_text=1` adds review and reply text (never for healthcare businesses; Yelp reviews only with `yelp_consent=true` and a recorded Yelp consent: `text_status` says why, `withheld_healthcare` or `withheld_yelp`), `include_removed=1` adds reviews removed from their site, `updated_since` (ISO 8601) only reviews changed since then. The plan's review window applies. Scope: `reviews:read`. JSON `{data: [rows], meta}` or `format=csv`. Rows of every business the credential reaches, by business, then in a stable order; columns in `meta.columns`.",
                "operationId": "v1ReportReviews",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReportCompany"
                    },
                    {
                        "$ref": "#/components/parameters/ReportStartDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportEndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportLimit"
                    },
                    {
                        "$ref": "#/components/parameters/ReportCursor"
                    },
                    {
                        "$ref": "#/components/parameters/ReportPage"
                    },
                    {
                        "$ref": "#/components/parameters/ReportFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ReportKey"
                    },
                    {
                        "name": "include_text",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "include_removed",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "updated_since",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (JSON or CSV)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReportPageMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/reports/review-metrics": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Report: review metrics",
                "description": "Time series per business and period (UTC), `breakdown=platform` also per review platform: new reviews, average rating, five-star and 1-2 star reviews, replies, reply rate, median response hours, running totals. Every period has a row. Scope: `reviews:read`. JSON `{data: [rows], meta}` or `format=csv`. Rows of every business the credential reaches, by business, then in a stable order; columns in `meta.columns`.",
                "operationId": "v1ReportReviewMetrics",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReportCompany"
                    },
                    {
                        "$ref": "#/components/parameters/ReportStartDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportEndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportInterval"
                    },
                    {
                        "name": "breakdown",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "none",
                                "platform"
                            ]
                        }
                    },
                    {
                        "$ref": "#/components/parameters/ReportLimit"
                    },
                    {
                        "$ref": "#/components/parameters/ReportCursor"
                    },
                    {
                        "$ref": "#/components/parameters/ReportPage"
                    },
                    {
                        "$ref": "#/components/parameters/ReportFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ReportKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (JSON or CSV)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReportPageMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/reports/review-requests": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Report: review requests",
                "description": "Time series per business and period (UTC): review requests created, sent, opened, clicked and reviewed, each on the day it happened. Scope: `reviews:read`. JSON `{data: [rows], meta}` or `format=csv`. Rows of every business the credential reaches, by business, then in a stable order; columns in `meta.columns`.",
                "operationId": "v1ReportReviewRequests",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReportCompany"
                    },
                    {
                        "$ref": "#/components/parameters/ReportStartDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportEndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportInterval"
                    },
                    {
                        "$ref": "#/components/parameters/ReportLimit"
                    },
                    {
                        "$ref": "#/components/parameters/ReportCursor"
                    },
                    {
                        "$ref": "#/components/parameters/ReportPage"
                    },
                    {
                        "$ref": "#/components/parameters/ReportFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ReportKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (JSON or CSV)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReportPageMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/reports/scores": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Report: Grades.com Score history",
                "description": "Grades.com Score history of the business's directory listing, one row per day and variant. Scope: `reviews:read`. JSON `{data: [rows], meta}` or `format=csv`. Rows of every business the credential reaches, by business, then in a stable order; columns in `meta.columns`.",
                "operationId": "v1ReportScores",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReportCompany"
                    },
                    {
                        "$ref": "#/components/parameters/ReportStartDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportEndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportLimit"
                    },
                    {
                        "$ref": "#/components/parameters/ReportCursor"
                    },
                    {
                        "$ref": "#/components/parameters/ReportPage"
                    },
                    {
                        "$ref": "#/components/parameters/ReportFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ReportKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (JSON or CSV)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReportPageMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/reports/ai-reputation": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Report: AI Reputation",
                "description": "AI Reputation answers over time (plan feature `ai_reputation`; businesses without it are in `meta.skipped`). Scope: `reviews:read`. JSON `{data: [rows], meta}` or `format=csv`. Rows of every business the credential reaches, by business, then in a stable order; columns in `meta.columns`.",
                "operationId": "v1ReportAiReputation",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReportCompany"
                    },
                    {
                        "$ref": "#/components/parameters/ReportStartDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportEndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportLimit"
                    },
                    {
                        "$ref": "#/components/parameters/ReportCursor"
                    },
                    {
                        "$ref": "#/components/parameters/ReportPage"
                    },
                    {
                        "$ref": "#/components/parameters/ReportFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ReportKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (JSON or CSV)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReportPageMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/reports/competitors": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Report: competitors",
                "description": "Monthly Competitor Map snapshots, one row per month and competitor (plan feature `competitor_map`; businesses without it are in `meta.skipped`). Scope: `reviews:read`. JSON `{data: [rows], meta}` or `format=csv`. Rows of every business the credential reaches, by business, then in a stable order; columns in `meta.columns`.",
                "operationId": "v1ReportCompetitors",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ReportCompany"
                    },
                    {
                        "$ref": "#/components/parameters/ReportStartDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportEndDate"
                    },
                    {
                        "$ref": "#/components/parameters/ReportLimit"
                    },
                    {
                        "$ref": "#/components/parameters/ReportCursor"
                    },
                    {
                        "$ref": "#/components/parameters/ReportPage"
                    },
                    {
                        "$ref": "#/components/parameters/ReportFormat"
                    },
                    {
                        "$ref": "#/components/parameters/ReportKey"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK (JSON or CSV)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/V1ReportPageMeta"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    },
                    {
                        "reportUrlKey": []
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/companies/{company}/flags/{flag}/filed": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Mark a review flag as filed",
                "description": "Scope: `reviews:write`. \"I filed it\": records that the report was filed with the site by hand, on `filed_at` (default now; not in the future). The flag becomes `submitted` and Grades then watches whether the review is removed (`report`). 409 when the flag is closed.",
                "operationId": "v1FlagFiled",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "filed_at": {
                                        "type": "string",
                                        "format": "date",
                                        "nullable": true
                                    },
                                    "external_reference": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 255
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewFlag"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            }
        },
        "/v1/companies/{company}/reviews/{review}/handling": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "How a review is replied to and reported",
                "description": "Scope: `reviews:read`. How a reply to and a report of this review are handled.",
                "operationId": "v1ReviewHandling",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    },
                    {
                        "$ref": "#/components/parameters/ReviewPath"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "reply": {
                                                    "$ref": "#/components/schemas/V1ReviewHandling"
                                                },
                                                "report": {
                                                    "$ref": "#/components/schemas/V1ReviewHandling"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/companies/{company}/sources/handling": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "How each connected review site is handled",
                "description": "Scope: `companies:read`. Per connected review source: how replies and reports are handled (`reply`, `report`, each a V1ReviewHandling without review-specific links).",
                "operationId": "v1SourcesHandling",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1SourceHandling"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/admin/review-sites": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List the review-site catalog",
                "description": "Super admins, scope `companies:write`. Every site of the catalog with its definition, live state and last verification run. Filters: `kind`, `source_type`, `verified` (true/false), `origin`.",
                "operationId": "v1AdminListReviewSites",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1AdminReviewSite"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            },
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Add a review site",
                "description": "Super admins, scope `companies:write`. Adds a catalog-only Apify driver, unverified: it is recognized by the radar right away and becomes connectable, parsed and scheduled once a verification run passes (`POST .../{slug}/verify`). `actor_id`, `input_template` (must use `{url}`; `{max}` and `{since}` are filled in) and `field_map` (targets id, rating, date, text, author, ...; see docs/apify-sources.md) can come later. `hosts` is the profile-URL host allowlist.",
                "operationId": "v1AdminCreateReviewSite",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "slug",
                                    "label",
                                    "hosts"
                                ],
                                "properties": {
                                    "slug": {
                                        "type": "string",
                                        "pattern": "^[a-z][a-z0-9_]{1,31}$",
                                        "example": "vagaro"
                                    },
                                    "label": {
                                        "type": "string",
                                        "example": "Vagaro",
                                        "maxLength": 100,
                                        "minLength": 1
                                    },
                                    "source_type": {
                                        "type": "string",
                                        "enum": [
                                            "customer_reviews",
                                            "employer_reviews",
                                            "directory",
                                            "aggregator"
                                        ]
                                    },
                                    "hosts": {
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 100
                                        },
                                        "example": [
                                            "vagaro.com"
                                        ],
                                        "maxItems": 20,
                                        "minItems": 1
                                    },
                                    "profile_patterns": {
                                        "description": "PCRE patterns for the URL path of a business profile.",
                                        "type": "array",
                                        "items": {
                                            "type": "string",
                                            "maxLength": 300
                                        },
                                        "maxItems": 10
                                    },
                                    "actor_id": {
                                        "type": "string",
                                        "example": "getdataforme/vagaro-reviews-scraper",
                                        "nullable": true,
                                        "maxLength": 191
                                    },
                                    "input_template": {
                                        "type": "object",
                                        "nullable": true,
                                        "additionalProperties": true
                                    },
                                    "field_map": {
                                        "type": "object",
                                        "nullable": true,
                                        "additionalProperties": true
                                    },
                                    "options": {
                                        "description": "newest_first, max_items, full_max_items, price {start, item}, max_charge_usd, items_path, display, ...",
                                        "type": "object",
                                        "nullable": true,
                                        "additionalProperties": true
                                    },
                                    "display": {
                                        "description": "Display settings of the site (free-form).",
                                        "type": "object",
                                        "additionalProperties": true
                                    },
                                    "schedule_at": {
                                        "type": "string",
                                        "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                        "example": "02:40",
                                        "nullable": true
                                    },
                                    "enabled": {
                                        "type": "boolean"
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true,
                                        "maxLength": 2000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AdminReviewSite"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/admin/review-sites/{slug}/verify": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Verify a review site",
                "description": "Super admins, scope `companies:write`. Runs the site's actor once on `url` (a real business profile with reviews; at most `max_items`, default 20, charge-capped at $0.50) and checks that id, author, rating 1-5, date and text are present in at least 80% of the reviews. A catalog site becomes verified (live) when the run passes; a code-defined site only gets the record. Waits up to 40 s: 200 with the result, or 202 while the run continues (the worker finishes it within a minute after it ends; read the site again for `verification`).",
                "operationId": "v1AdminVerifyReviewSite",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "url"
                                ],
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "format": "url"
                                    },
                                    "max_items": {
                                        "type": "integer",
                                        "maximum": 20,
                                        "minimum": 1
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Finished: `data.verification.status` passed, failed or error.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AdminReviewSite"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "202": {
                        "description": "Still running: `data.verification.status` is running.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1AdminReviewSite"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "502": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/admin/review-site-candidates": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List site radar candidates",
                "description": "Super admins, scope `companies:write`. The site radar: review-site domains found across all companies by the weekly `radar:site-report`, best first. Filters: `status` (comma-separated), `qualifies` (true/false), `classification`, `limit` (default 50, max 200), `sort` (`demand`, the default: most customer companies that need the site first, then explicit requests, then score; or `score`). Each row carries the demand queue (`demand_customers`, `demand_requests`, `demand_sources`).",
                "operationId": "v1AdminListReviewSiteCandidates",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewSiteCandidate"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "total": {
                                                    "type": "integer"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/admin/review-site-candidates/demand": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Record demand for a review site",
                "description": "Super admins, scope `companies:write`. Records demand for a review site (docs/review-radar.md \"Demand queue\"): `domain` or `url`, optionally on behalf of a `company` (uuid) and with a `note`. The request is kept (`review_site_requests`, origin admin) and the candidate (created when missing) gains it at once; the daily `review-sites:demand` recomputes the same way.",
                "operationId": "v1AdminRecordReviewSiteDemand",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "domain": {
                                        "type": "string",
                                        "example": "classpass.com"
                                    },
                                    "url": {
                                        "type": "string",
                                        "format": "url"
                                    },
                                    "company": {
                                        "description": "Company uuid",
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "note": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Recorded",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewSiteCandidate"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/admin/review-site-candidates/{candidate}": {
            "patch": {
                "tags": [
                    "v1"
                ],
                "summary": "Update a site radar candidate",
                "description": "Super admins, scope `companies:write`. Sets a candidate's `status` (`ignored` and `not_reviews` are kept by later reports; `verified` / `building` follow the catalog), `notes` or `site_slug`.",
                "operationId": "v1AdminUpdateReviewSiteCandidate",
                "parameters": [
                    {
                        "name": "candidate",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "new",
                                            "building",
                                            "verified",
                                            "ignored",
                                            "not_reviews"
                                        ]
                                    },
                                    "notes": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "site_slug": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ReviewSiteCandidate"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/review-sites": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List connectable review sites",
                "description": "Scope: `companies:read`. The review sites that can be connected now: native sites (Google and Facebook connect through the dashboard, `connect: oauth`) and the verified Apify-backed sites of the catalog, customer-review sites only. Same list for every member; a site added to the catalog appears here once it is verified, without a release. Also at `GET /api/review-sites` for the dashboard session.",
                "operationId": "v1ListReviewSites",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ReviewSite"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "site_requests": {
                                                    "description": "true: a site that is not listed can be requested with `POST /v1/companies/{company}/sources/requests`.",
                                                    "type": "boolean"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/companies/{company}/integrations/shopify/claim": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Link a Shopify store",
                "description": "Scope: `companies:write`, company admins, plan feature `review_requests`. Links the Shopify store that installed the Grades.com app (the `claim` of `my.grades.com/integrations/shopify?claim=`, single use, 60 minutes) to this company: stores the connection, subscribes the order webhooks and writes the storefront key. `dry_run: true` only answers the store's domain. 410 `claim_expired`, 409 `shop_linked_elsewhere`.",
                "operationId": "v1ShopifyClaim",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "claim"
                                ],
                                "properties": {
                                    "claim": {
                                        "type": "string"
                                    },
                                    "dry_run": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The connection (V1Integration), or with `dry_run` only `{shop}` (the store's domain)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "anyOf": [
                                                {
                                                    "$ref": "#/components/schemas/V1Integration"
                                                },
                                                {
                                                    "required": [
                                                        "shop"
                                                    ],
                                                    "properties": {
                                                        "shop": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "type": "object",
                                                    "additionalProperties": false
                                                }
                                            ]
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "410": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:write"
                ]
            }
        },
        "/v1/companies/{company}/integrations/shopify/privacy-requests": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Shopify privacy requests",
                "description": "Scope: `companies:read`, company admins. The Shopify privacy webhooks that concerned this company (customers/data_request, customers/redact, shop/redact), newest first: ids and counts only. A data request has a report to download for 30 days (`report_available`).",
                "operationId": "v1ShopifyPrivacyRequests",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/V1ShopifyPrivacyRequest"
                                            }
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/companies/{company}/integrations/shopify/privacy-requests/{request}": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "Shopify data request report",
                "description": "Scope: `companies:read`, company admins. The report of a customers/data_request: the contacts, review requests and order events Grades.com holds for that Shopify customer, for the business to send on. 404 once the report expired.",
                "operationId": "v1ShopifyPrivacyReport",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CompanyPath"
                    },
                    {
                        "name": "request",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1ShopifyPrivacyReport"
                                        },
                                        "meta": {
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        },
        "/v1/companies/{company}/reviews/{review}/translation": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Translate a review into English",
                "description": "Scope: `reviews:read`. The English translation of a review that is not in English (machine translation, labeled \"Translated by AI\"; the original stays the text of record). Made once with one model call and kept; later calls answer the stored one. `status` `unavailable` with `reason` `language_unsupported` (healthcare review in a language the clinical scrub cannot read: never sent to a model), `yelp_text` (Yelp text is never sent to a model) or `failed`. 422 `translation_not_needed` when the review is in English, its language cannot be told or it has no text.",
                "operationId": "v1TranslateReview",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/V1Translation"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:read"
                ]
            }
        },
        "/v1/companies/{company}/agent/actions/{action}/translate": {
            "post": {
                "tags": [
                    "v1"
                ],
                "summary": "Translate an edited reply into the reply language",
                "description": "Scope: `reviews:write`. \"Translate my edit\": translates the owner's edited reply (normally written in English) into the language of the reply draft, with one model call. Nothing is saved on the action and nothing is posted: approve the answer's `text` (POST .../approve with `text`) to use it; its `draft_en` is then the owner's own words. 409 `translation_not_needed` when the reply is in English or its language is unknown; 422 for an empty text or (healthcare) care details in the edit; 429 when the business used today's translations.",
                "operationId": "v1TranslateAgentDraftEdit",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "maxLength": 4000
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "properties": {
                                                "text": {
                                                    "description": "The edit in the reply language.",
                                                    "type": "string"
                                                },
                                                "language": {
                                                    "type": "string",
                                                    "example": "es"
                                                },
                                                "text_en": {
                                                    "description": "The text that was sent.",
                                                    "type": "string"
                                                },
                                                "label": {
                                                    "type": "string",
                                                    "example": "Translated by AI"
                                                },
                                                "machine_translated": {
                                                    "type": "boolean",
                                                    "example": true
                                                },
                                                "model": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "404": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "409": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "422": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "429": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "reviews:write"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "reviews:write"
                ]
            }
        },
        "/v1/admin/waitlist": {
            "get": {
                "tags": [
                    "v1"
                ],
                "summary": "List waitlist signups",
                "description": "Super admins, scope `companies:read`. Waitlist / contact form submissions of www.grades.com, newest first. Filters: `status` (comma-separated: new, contacted, converted, unsubscribed), `since` (date or date-time, created at or after), `email`, `origin` (`form`, or an import source such as `hubspot-import`). Page with `cursor` = the previous response's `meta.next_cursor`. The IP address is never returned (only an HMAC of it is stored).",
                "operationId": "v1AdminListWaitlist",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "since",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "2026-10-01"
                        }
                    },
                    {
                        "name": "email",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "origin",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "form"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "maximum": 200,
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object"
                                            }
                                        },
                                        "meta": {
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                },
                                                "total": {
                                                    "type": "integer"
                                                },
                                                "next_cursor": {
                                                    "type": "integer",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/V1Problem"
                    },
                    "403": {
                        "$ref": "#/components/responses/V1Problem"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    },
                    {
                        "oauth2": [
                            "companies:read"
                        ]
                    }
                ],
                "x-required-scopes": [
                    "companies:read"
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "AssistantConversationSummary": {
                "required": [
                    "id",
                    "title",
                    "origin",
                    "created_at",
                    "last_message_at",
                    "questions"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "title": {
                        "type": "string"
                    },
                    "origin": {
                        "description": "Where it was asked: dashboard, slack, google_chat, teams or android.",
                        "type": "string"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_message_at": {
                        "description": "Null in a single conversation's payload.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "questions": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "AssistantMeta": {
                "required": [
                    "enabled",
                    "usage"
                ],
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "usage": {
                        "description": "Questions this month (`limit`/`remaining` null when the plan does not cap them).",
                        "required": [
                            "used",
                            "limit",
                            "remaining"
                        ],
                        "properties": {
                            "used": {
                                "type": "integer"
                            },
                            "limit": {
                                "type": "integer",
                                "nullable": true
                            },
                            "remaining": {
                                "type": "integer",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1AgentPolicyCheck": {
                "description": "Where one review stands in Review Disputes, with the review, the broken rule and the flag action.",
                "properties": {
                    "review": {
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "rating": {
                                "type": "integer",
                                "nullable": true,
                                "maximum": 5,
                                "minimum": 1
                            },
                            "author": {
                                "type": "string",
                                "nullable": true
                            },
                            "text": {
                                "type": "string",
                                "nullable": true
                            },
                            "published_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "removed": {
                                "type": "boolean"
                            },
                            "external_url": {
                                "type": "string",
                                "nullable": true
                            },
                            "company": {
                                "properties": {
                                    "uuid": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "name": {
                                        "type": "string"
                                    },
                                    "location_nickname": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        },
                        "type": "object"
                    },
                    "rule": {
                        "description": "The site rule the flag action names, if any.",
                        "type": "string",
                        "nullable": true
                    },
                    "action": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1AgentAction"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "not_checked",
                            "report",
                            "reported",
                            "honest",
                            "dismissed",
                            "expired"
                        ]
                    },
                    "checkable": {
                        "type": "boolean"
                    },
                    "reason": {
                        "description": "Why it cannot be checked now.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "removed",
                            "no_review_site",
                            "not_low_rated",
                            "plan",
                            "role",
                            "limit"
                        ]
                    },
                    "site": {
                        "type": "string"
                    },
                    "site_name": {
                        "type": "string"
                    },
                    "max_rating": {
                        "description": "Highest rating that counts as low-rated.",
                        "type": "integer"
                    },
                    "case": {
                        "description": "The Review Disputes case of the review.",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "new",
                                    "contacted",
                                    "resolved",
                                    "closed"
                                ]
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "automatic": {
                        "description": "The agent checks new low-rated reviews by itself.",
                        "type": "boolean"
                    },
                    "checks_left_today": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1AgencyClient": {
                "description": "A client business of an agency with its plan, billing state, review stats for the period over the business and its locations, connections and the latest AI Reputation run.",
                "required": [
                    "company",
                    "plan",
                    "plan_name",
                    "locations",
                    "joined_at",
                    "billing",
                    "stats",
                    "connections",
                    "ai_reputation"
                ],
                "properties": {
                    "company": {
                        "required": [
                            "uuid",
                            "name",
                            "slug",
                            "city",
                            "state"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            },
                            "slug": {
                                "type": "string"
                            },
                            "city": {
                                "type": "string",
                                "nullable": true
                            },
                            "state": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "plan": {
                        "description": "The client's agency plan.",
                        "type": "string"
                    },
                    "plan_name": {
                        "type": "string"
                    },
                    "locations": {
                        "description": "The business and its locations.",
                        "type": "integer"
                    },
                    "joined_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "billing": {
                        "required": [
                            "status",
                            "source",
                            "billed",
                            "not_billed_reason",
                            "until",
                            "trial_ends_at"
                        ],
                        "properties": {
                            "status": {
                                "description": "The business's billing status.",
                                "type": "string"
                            },
                            "source": {
                                "description": "Where its plan comes from (own, agency, HQ, grace, trial, ...).",
                                "type": "string"
                            },
                            "billed": {
                                "description": "true: on the agency's bill.",
                                "type": "boolean"
                            },
                            "not_billed_reason": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "trial",
                                    "own_subscription",
                                    "offboarded"
                                ]
                            },
                            "until": {
                                "description": "When a not-billed reason ends (trial end, own renewal), if known.",
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "trial_ends_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "stats": {
                        "description": "Over the period (`meta.from`/`meta.to`), the business and its locations.",
                        "required": [
                            "reviews_total",
                            "rating_average",
                            "new_reviews",
                            "new_rating_average",
                            "response_rate",
                            "unanswered_negative",
                            "pending_agent_actions",
                            "low_ratings",
                            "unanswered"
                        ],
                        "properties": {
                            "reviews_total": {
                                "type": "integer"
                            },
                            "rating_average": {
                                "type": "number",
                                "nullable": true
                            },
                            "new_reviews": {
                                "type": "integer"
                            },
                            "new_rating_average": {
                                "type": "number",
                                "nullable": true
                            },
                            "response_rate": {
                                "description": "0-1.",
                                "type": "number",
                                "nullable": true
                            },
                            "unanswered_negative": {
                                "type": "integer"
                            },
                            "pending_agent_actions": {
                                "type": "integer"
                            },
                            "low_ratings": {
                                "type": "integer"
                            },
                            "unanswered": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "connections": {
                        "description": "The worst of the business's and its locations' review-site connections.",
                        "required": [
                            "status",
                            "google",
                            "issues"
                        ],
                        "properties": {
                            "status": {
                                "type": "string",
                                "enum": [
                                    "ok",
                                    "attention"
                                ]
                            },
                            "google": {
                                "type": "string",
                                "enum": [
                                    "connected",
                                    "reconnect",
                                    "not_connected"
                                ]
                            },
                            "issues": {
                                "type": "array",
                                "items": {
                                    "required": [
                                        "platform",
                                        "name",
                                        "state",
                                        "location"
                                    ],
                                    "properties": {
                                        "platform": {
                                            "type": "string"
                                        },
                                        "name": {
                                            "type": "string"
                                        },
                                        "state": {
                                            "type": "string",
                                            "enum": [
                                                "reconnect",
                                                "failing",
                                                "not_connected"
                                            ]
                                        },
                                        "location": {
                                            "required": [
                                                "uuid",
                                                "name",
                                                "location_nickname"
                                            ],
                                            "properties": {
                                                "uuid": {
                                                    "type": "string",
                                                    "format": "uuid"
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "location_nickname": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "ai_reputation": {
                        "description": "The latest AI Reputation run in short; null before the first run.",
                        "required": [
                            "mentioned",
                            "sentiment",
                            "engines",
                            "last_run_at"
                        ],
                        "properties": {
                            "mentioned": {
                                "description": "Mentioned by `count` of `of` assistants.",
                                "required": [
                                    "count",
                                    "of"
                                ],
                                "properties": {
                                    "count": {
                                        "type": "integer"
                                    },
                                    "of": {
                                        "type": "integer"
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            },
                            "sentiment": {
                                "description": "The most common sentiment.",
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "positive",
                                    "mixed",
                                    "negative"
                                ]
                            },
                            "engines": {
                                "type": "integer"
                            },
                            "last_run_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgencyClientTotals": {
                "description": "Review stats over every listed client and its locations for the period.",
                "required": [
                    "reviews_total",
                    "rating_average",
                    "new_reviews",
                    "new_rating_average",
                    "previous_new_reviews",
                    "previous_rating_average",
                    "responded",
                    "response_rate",
                    "unanswered_negative",
                    "rating_distribution",
                    "pending_agent_actions",
                    "low_ratings",
                    "unanswered"
                ],
                "properties": {
                    "reviews_total": {
                        "type": "integer"
                    },
                    "rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "new_reviews": {
                        "type": "integer"
                    },
                    "new_rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "previous_new_reviews": {
                        "type": "integer"
                    },
                    "previous_rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "responded": {
                        "type": "integer"
                    },
                    "response_rate": {
                        "description": "0-1.",
                        "type": "number",
                        "nullable": true
                    },
                    "unanswered_negative": {
                        "type": "integer"
                    },
                    "rating_distribution": {
                        "description": "New reviews per star rating, keys `5` to `1`.",
                        "type": "object",
                        "additionalProperties": {
                            "type": "integer"
                        }
                    },
                    "pending_agent_actions": {
                        "type": "integer"
                    },
                    "low_ratings": {
                        "type": "integer"
                    },
                    "unanswered": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1AgencyClientRequest": {
                "description": "An agency's request to take on a business.",
                "required": [
                    "uuid",
                    "agency",
                    "company",
                    "plan",
                    "status",
                    "message",
                    "requested_by",
                    "created_at",
                    "expires_at",
                    "decided_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "agency": {
                        "$ref": "#/components/schemas/V1AgencyRef"
                    },
                    "company": {
                        "$ref": "#/components/schemas/V1AgencyCompanyRef"
                    },
                    "plan": {
                        "type": "string"
                    },
                    "status": {
                        "description": "A pending request past its expiry reads `expired`.",
                        "type": "string",
                        "enum": [
                            "pending",
                            "accepted",
                            "declined",
                            "cancelled",
                            "expired"
                        ]
                    },
                    "message": {
                        "type": "string",
                        "nullable": true
                    },
                    "requested_by": {
                        "required": [
                            "name"
                        ],
                        "properties": {
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "decided_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgencyBilling": {
                "description": "The agency's bill (docs/agencies.md \"Billing\"). Amounts are whole US dollars (display prices).",
                "required": [
                    "mode",
                    "status",
                    "locked",
                    "lock_at",
                    "interval",
                    "renews_at",
                    "cancel_at",
                    "discount_percent",
                    "prices",
                    "lines",
                    "estimated_total",
                    "not_billed",
                    "billing_company",
                    "checkout_available",
                    "checkout_unavailable_reason",
                    "portal_available"
                ],
                "properties": {
                    "mode": {
                        "type": "string",
                        "enum": [
                            "stripe",
                            "unconfigured"
                        ]
                    },
                    "status": {
                        "description": "The agency subscription; `none` without one.",
                        "type": "string",
                        "enum": [
                            "active",
                            "trialing",
                            "past_due",
                            "canceled",
                            "none",
                            "unconfigured"
                        ]
                    },
                    "locked": {
                        "type": "boolean"
                    },
                    "lock_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "interval": {
                        "type": "string",
                        "enum": [
                            "monthly",
                            "yearly"
                        ]
                    },
                    "renews_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "cancel_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "discount_percent": {
                        "type": "integer"
                    },
                    "prices": {
                        "description": "Agency prices per plan the agency sells, keyed by plan.",
                        "type": "object",
                        "additionalProperties": {
                            "required": [
                                "monthly",
                                "yearly",
                                "location_monthly",
                                "location_yearly"
                            ],
                            "properties": {
                                "monthly": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "yearly": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "location_monthly": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "location_yearly": {
                                    "type": "integer",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "lines": {
                        "type": "array",
                        "items": {
                            "required": [
                                "plan",
                                "plan_name",
                                "kind",
                                "quantity",
                                "unit_price",
                                "interval"
                            ],
                            "properties": {
                                "plan": {
                                    "type": "string"
                                },
                                "plan_name": {
                                    "type": "string"
                                },
                                "kind": {
                                    "description": "`base`: client businesses; `location`: their extra locations.",
                                    "type": "string",
                                    "enum": [
                                        "base",
                                        "location"
                                    ]
                                },
                                "quantity": {
                                    "type": "integer"
                                },
                                "unit_price": {
                                    "description": "Null when no price is configured.",
                                    "type": "integer",
                                    "nullable": true
                                },
                                "interval": {
                                    "type": "string",
                                    "enum": [
                                        "monthly",
                                        "yearly"
                                    ]
                                }
                            },
                            "type": "object"
                        }
                    },
                    "estimated_total": {
                        "type": "integer"
                    },
                    "not_billed": {
                        "description": "Clients left off the bill and why.",
                        "type": "array",
                        "items": {
                            "required": [
                                "company",
                                "reason",
                                "until"
                            ],
                            "properties": {
                                "company": {
                                    "$ref": "#/components/schemas/V1AgencyCompanyRef"
                                },
                                "reason": {
                                    "type": "string",
                                    "enum": [
                                        "trial",
                                        "own_subscription",
                                        "offboarded"
                                    ]
                                },
                                "until": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "billing_company": {
                        "required": [
                            "uuid",
                            "name"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "checkout_available": {
                        "type": "boolean"
                    },
                    "checkout_unavailable_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "portal_available": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1AgencyClientInvitation": {
                "description": "An agency's e-mail invitation to a business owner (never its link). `listing` is the directory listing the agency picked; `company` the business that joined, once accepted.",
                "required": [
                    "uuid",
                    "agency",
                    "email",
                    "business_name",
                    "listing",
                    "plan",
                    "message",
                    "status",
                    "invited_by",
                    "company",
                    "created_at",
                    "sent_at",
                    "expires_at",
                    "accepted_at",
                    "declined_at",
                    "revoked_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "agency": {
                        "$ref": "#/components/schemas/V1AgencyRef"
                    },
                    "email": {
                        "type": "string"
                    },
                    "business_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "listing": {
                        "required": [
                            "id",
                            "name",
                            "city",
                            "state"
                        ],
                        "properties": {
                            "id": {
                                "description": "Public directory listing id.",
                                "type": "integer"
                            },
                            "name": {
                                "type": "string"
                            },
                            "city": {
                                "type": "string",
                                "nullable": true
                            },
                            "state": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "plan": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "accepted",
                            "declined",
                            "revoked",
                            "expired"
                        ]
                    },
                    "invited_by": {
                        "required": [
                            "name"
                        ],
                        "properties": {
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "company": {
                        "required": [
                            "uuid",
                            "name"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "sent_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "accepted_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "declined_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "revoked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgencyRef": {
                "description": "An agency in short.",
                "required": [
                    "uuid",
                    "slug",
                    "name"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1AgencyCompanyRef": {
                "description": "A business in short.",
                "required": [
                    "uuid",
                    "name"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1Agency": {
                "description": "An agency as the caller sees it (docs/agencies.md \"Payloads\").",
                "required": [
                    "uuid",
                    "slug",
                    "name",
                    "status",
                    "membership",
                    "allowed_plans",
                    "default_plan",
                    "hub",
                    "white_label",
                    "billing_company",
                    "clients_count",
                    "pending_requests_count",
                    "created_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "suspended"
                        ]
                    },
                    "membership": {
                        "description": "The caller's membership; null when the caller has none (a platform super admin who is not a member, or a credential limited to some businesses).",
                        "required": [
                            "role",
                            "all_clients",
                            "accepted",
                            "assigned_clients"
                        ],
                        "properties": {
                            "role": {
                                "type": "string",
                                "enum": [
                                    "admin",
                                    "member"
                                ]
                            },
                            "all_clients": {
                                "type": "boolean"
                            },
                            "accepted": {
                                "type": "boolean"
                            },
                            "assigned_clients": {
                                "description": "Clients assigned to the caller; 0 with `all_clients`.",
                                "type": "integer"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "allowed_plans": {
                        "description": "The plans the agency sells (every plan when not limited).",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "starter",
                                "pro",
                                "premium"
                            ]
                        }
                    },
                    "default_plan": {
                        "type": "string",
                        "enum": [
                            "starter",
                            "pro",
                            "premium"
                        ]
                    },
                    "hub": {
                        "description": "true: the Client Hub's agency.",
                        "type": "boolean"
                    },
                    "white_label": {
                        "required": [
                            "host",
                            "verified",
                            "mcp_url"
                        ],
                        "properties": {
                            "host": {
                                "type": "string",
                                "nullable": true
                            },
                            "verified": {
                                "type": "boolean"
                            },
                            "mcp_url": {
                                "description": "`https://<host>/mcp` once the host is verified, else null.",
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "billing_company": {
                        "description": "The business that holds the agency subscription.",
                        "required": [
                            "uuid",
                            "name"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "clients_count": {
                        "type": "integer"
                    },
                    "pending_requests_count": {
                        "type": "integer"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgencyMember": {
                "description": "A member of an agency (accepted or pending).",
                "required": [
                    "user",
                    "role",
                    "role_on_clients",
                    "all_clients",
                    "accepted",
                    "accepted_at",
                    "invited_at",
                    "clients"
                ],
                "properties": {
                    "user": {
                        "required": [
                            "uuid",
                            "name",
                            "email"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            },
                            "email": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "role": {
                        "type": "string",
                        "enum": [
                            "admin",
                            "member"
                        ]
                    },
                    "role_on_clients": {
                        "description": "The role on the clients (www/docs/roles.md section 3): the one set, or the default of the agency role (admin -> `owner`, member -> legacy `user`).",
                        "type": "string",
                        "enum": [
                            "owner",
                            "super_admin",
                            "admin",
                            "approver",
                            "reviewer",
                            "viewer",
                            "user"
                        ]
                    },
                    "all_clients": {
                        "type": "boolean"
                    },
                    "accepted": {
                        "type": "boolean"
                    },
                    "accepted_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "invited_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "clients": {
                        "description": "The client businesses assigned to a member without all clients, by name.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AgencyCompanyRef"
                        }
                    }
                },
                "type": "object"
            },
            "V1AgencyInvitation": {
                "description": "An e-mail invitation to join the agency (never its link).",
                "required": [
                    "uuid",
                    "email",
                    "role",
                    "all_clients",
                    "clients",
                    "status",
                    "invited_by",
                    "created_at",
                    "expires_at",
                    "accepted_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "email": {
                        "type": "string"
                    },
                    "role": {
                        "type": "string",
                        "enum": [
                            "admin",
                            "member"
                        ]
                    },
                    "all_clients": {
                        "type": "boolean"
                    },
                    "clients": {
                        "description": "Client businesses the invitee will be assigned (empty with `all_clients`).",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AgencyCompanyRef"
                        }
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "accepted",
                            "revoked",
                            "expired"
                        ]
                    },
                    "invited_by": {
                        "required": [
                            "name"
                        ],
                        "properties": {
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "accepted_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgentTriageResult": {
                "properties": {
                    "reviews_triaged": {
                        "type": "integer"
                    },
                    "reviews_skipped": {
                        "description": "Already replied to, or queued by a concurrent run.",
                        "type": "integer"
                    },
                    "actions_created": {
                        "type": "integer"
                    },
                    "reply_actions": {
                        "type": "integer"
                    },
                    "flag_actions": {
                        "type": "integer"
                    },
                    "executed": {
                        "description": "Replies auto-posted (auto_positive, auto_all).",
                        "type": "integer"
                    },
                    "failed": {
                        "description": "Auto-posts the site refused.",
                        "type": "integer"
                    },
                    "pending": {
                        "description": "Actions awaiting approval.",
                        "type": "integer"
                    },
                    "escalated": {
                        "description": "Reply mode `auto_all`: replies kept for a person (part of `pending`).",
                        "type": "integer"
                    },
                    "scheduled": {
                        "description": "Reply mode `auto_all`: checked replies waiting for the end of the quiet hours, or for the next day when the daily cap is reached (part of `pending`).",
                        "type": "integer"
                    },
                    "llm_calls": {
                        "type": "integer"
                    },
                    "ai_cap_reached": {
                        "type": "boolean"
                    },
                    "window": {
                        "properties": {
                            "from": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "until": {
                                "type": "string",
                                "format": "date-time"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1AgentSettingsUpdate": {
                "description": "The body of `PUT .../agent/settings`: the fields to save (at least one).",
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "reply_mode": {
                        "type": "string",
                        "enum": [
                            "off",
                            "draft",
                            "approve",
                            "auto_positive",
                            "auto_all"
                        ]
                    },
                    "auto_post_min_rating": {
                        "type": "integer",
                        "maximum": 5,
                        "minimum": 1
                    },
                    "escalate_max_rating": {
                        "description": "Reviews rated this or lower are never auto-replied; 0 = no rating escalation (Premium hands-free, approval `none`; every other escalation still holds).",
                        "type": "integer",
                        "maximum": 4,
                        "minimum": 0
                    },
                    "auto_reply_daily_cap": {
                        "type": "integer",
                        "maximum": 200,
                        "minimum": 1
                    },
                    "quiet_hours_start": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 23,
                        "minimum": 0
                    },
                    "quiet_hours_end": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 23,
                        "minimum": 0
                    },
                    "flag_mode": {
                        "type": "string",
                        "enum": [
                            "off",
                            "draft"
                        ]
                    },
                    "flag_threshold": {
                        "type": "number",
                        "maximum": 1,
                        "minimum": 0
                    },
                    "browser_automation": {
                        "type": "boolean"
                    },
                    "include_contact_details": {
                        "type": "boolean",
                        "deprecated": true
                    },
                    "contact_signoff": {
                        "type": "boolean"
                    },
                    "contact_signoff_phone": {
                        "type": "boolean"
                    },
                    "contact_signoff_email": {
                        "type": "boolean"
                    },
                    "auto_post_languages": {
                        "description": "Languages (ISO 639-1) a reply may be auto-posted in; null or [] = the default [\"en\"].",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es",
                                "fr",
                                "pt",
                                "de",
                                "it",
                                "vi",
                                "tl",
                                "zh",
                                "ja",
                                "ko",
                                "ru",
                                "uk",
                                "ar",
                                "he",
                                "fa",
                                "hi",
                                "el",
                                "th",
                                "pl",
                                "ht"
                            ]
                        },
                        "nullable": true
                    },
                    "reply_language_mode": {
                        "description": "match_review (default), always_english or allowed_list (see V1AgentSettings).",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "match_review",
                            "always_english",
                            "allowed_list"
                        ]
                    },
                    "reply_languages": {
                        "description": "allowed_list: review languages (ISO 639-1) replied to in their own language.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es",
                                "fr",
                                "pt",
                                "de",
                                "it",
                                "vi",
                                "tl",
                                "zh",
                                "ja",
                                "ko",
                                "ru",
                                "uk",
                                "ar",
                                "he",
                                "fa",
                                "hi",
                                "el",
                                "th",
                                "pl",
                                "ht"
                            ]
                        },
                        "nullable": true
                    },
                    "tone": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "custom_instructions": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 1000
                    },
                    "report_mode": {
                        "type": "string",
                        "enum": [
                            "off",
                            "draft",
                            "auto"
                        ]
                    },
                    "report_rules": {
                        "$ref": "#/components/schemas/V1AgentReportRules"
                    },
                    "report_consent_version": {
                        "type": "string",
                        "nullable": true
                    },
                    "reply_voice": {
                        "properties": {
                            "preset": {
                                "type": "string",
                                "nullable": true
                            },
                            "custom": {
                                "type": "string",
                                "nullable": true,
                                "maxLength": 600
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "reply_signature": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 120
                    },
                    "approval": {
                        "properties": {
                            "replies": {
                                "type": "string",
                                "enum": [
                                    "all",
                                    "negative_only",
                                    "none"
                                ]
                            },
                            "reports": {
                                "type": "string",
                                "enum": [
                                    "all",
                                    "negative_only",
                                    "none"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "rules": {
                        "description": "The rule set (see V1AgentSettings.rules).",
                        "type": "object"
                    },
                    "reset": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "voice",
                                "reply",
                                "reports"
                            ]
                        }
                    }
                },
                "type": "object"
            },
            "V1AgentVoicePreview": {
                "description": "One reply drafted for a fixed sample review in the voice given; nothing saved.",
                "properties": {
                    "review": {
                        "description": "The fixed sample review.",
                        "properties": {
                            "rating": {
                                "type": "integer",
                                "maximum": 5,
                                "minimum": 1
                            },
                            "author": {
                                "type": "string"
                            },
                            "text": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "reply": {
                        "description": "The draft, with the signature appended.",
                        "type": "string"
                    },
                    "voice": {
                        "properties": {
                            "preset": {
                                "type": "string",
                                "nullable": true
                            },
                            "custom": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1AgentOutcomePeriod": {
                "properties": {
                    "from": {
                        "type": "string",
                        "format": "date"
                    },
                    "decided": {
                        "description": "Drafts a person approved, edited or rejected.",
                        "type": "integer"
                    },
                    "approved_as_is": {
                        "type": "integer"
                    },
                    "edited": {
                        "type": "integer"
                    },
                    "rejected": {
                        "type": "integer"
                    },
                    "auto_posted": {
                        "type": "integer"
                    },
                    "expired": {
                        "type": "integer"
                    },
                    "as_is_rate": {
                        "type": "number",
                        "nullable": true
                    },
                    "edit_rate": {
                        "type": "number",
                        "nullable": true
                    },
                    "rejection_rate": {
                        "type": "number",
                        "nullable": true
                    },
                    "avg_edit_ratio": {
                        "description": "Mean share of words changed in edits.",
                        "type": "number",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgentOutcomeSummary": {
                "properties": {
                    "scope": {
                        "type": "string",
                        "enum": [
                            "business",
                            "fleet"
                        ]
                    },
                    "this_month": {
                        "$ref": "#/components/schemas/V1AgentOutcomePeriod"
                    },
                    "last_month": {
                        "$ref": "#/components/schemas/V1AgentOutcomePeriod"
                    },
                    "weeks": {
                        "description": "The last 12 weeks, oldest first.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AgentOutcomePeriod"
                        }
                    },
                    "headline": {
                        "description": "\"86% of drafts approved without edits this month, up from 71%.\" Null with fewer than 5 decisions this month.",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgentLearnings": {
                "description": "What the review agent learned from this business and across Grades.com.",
                "properties": {
                    "business": {
                        "properties": {
                            "learnings": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/V1AgentLearning"
                                }
                            },
                            "profile": {
                                "properties": {
                                    "version": {
                                        "type": "integer"
                                    },
                                    "summary": {
                                        "type": "string"
                                    },
                                    "style": {
                                        "type": "object"
                                    },
                                    "updated_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            },
                            "improvement": {
                                "$ref": "#/components/schemas/V1AgentOutcomeSummary"
                            }
                        },
                        "type": "object"
                    },
                    "fleet": {
                        "properties": {
                            "learnings": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/V1FleetLearning"
                                }
                            },
                            "improvement": {
                                "$ref": "#/components/schemas/V1AgentOutcomeSummary"
                            },
                            "computed_on": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1AgentLearningDecision": {
                "description": "The learning after the decision: a learning of this business (V1AgentLearning) or, for a fleet learning, the fleet learning with this business's `override` (V1FleetLearning).",
                "oneOf": [
                    {
                        "$ref": "#/components/schemas/V1AgentLearning"
                    },
                    {
                        "$ref": "#/components/schemas/V1FleetLearning"
                    }
                ]
            },
            "V1AgentLocks": {
                "properties": {
                    "paths": {
                        "description": "The locked rule parts.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "reply_voice",
                                "custom_instructions",
                                "include_contact_details",
                                "reply_language",
                                "approval.replies",
                                "approval.reports",
                                "report_rules"
                            ]
                        }
                    },
                    "set_by": {
                        "description": "The HQ that locked them (null at the HQ itself or a single business).",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "applies": {
                        "description": "Whether the locks hold for the caller (never for the HQ's owners).",
                        "type": "boolean"
                    },
                    "editable": {
                        "description": "Whether the caller can change the locks (owners, at the HQ).",
                        "type": "boolean"
                    },
                    "available": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "reply_voice",
                                "custom_instructions",
                                "include_contact_details",
                                "reply_language",
                                "approval.replies",
                                "approval.reports",
                                "report_rules"
                            ]
                        }
                    }
                },
                "type": "object"
            },
            "V1AgentApprovers": {
                "properties": {
                    "routing": {
                        "description": "Who gets the approval notices now: `assigned` approvers, the company's owners and `admins`, the `hq_owners`, every `members` who can approve, or `none`.",
                        "type": "string",
                        "enum": [
                            "assigned",
                            "admins",
                            "hq_owners",
                            "members",
                            "none"
                        ]
                    },
                    "approvers": {
                        "description": "The people assigned.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AgentPerson"
                        }
                    },
                    "recipients": {
                        "description": "Who gets the notices (the routing above).",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AgentPerson"
                        }
                    },
                    "candidates": {
                        "description": "Who can be assigned.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AgentPerson"
                        }
                    }
                },
                "type": "object"
            },
            "V1AgentPerson": {
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string"
                    },
                    "role": {
                        "type": "string",
                        "nullable": true
                    },
                    "role_label": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AlertSettings": {
                "required": [
                    "ai_reputation_alerts",
                    "competitor_alerts",
                    "competitor_top_n",
                    "updated_at"
                ],
                "properties": {
                    "ai_reputation_alerts": {
                        "description": "Premium: after each AI Reputation check, an alert when an assistant's tone drops, it stops mentioning the business or describes another business, a rating it quotes is wrong or out of date, it cites a review site it never cited before, or it names a new competitor as an alternative. Effective value (an unsaved setting follows the default, `meta.defaults_on`).",
                        "type": "boolean"
                    },
                    "competitor_alerts": {
                        "description": "Premium: an alert when a competitor enters the top `competitor_top_n` of the Competitor Map, or a competitor's rating, reviews in the last 12 months or grade passes the business's.",
                        "type": "boolean"
                    },
                    "competitor_top_n": {
                        "type": "integer",
                        "default": 5,
                        "maximum": 20,
                        "minimum": 1
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AlertEvent": {
                "required": [
                    "uuid",
                    "feature",
                    "kind",
                    "title",
                    "detail",
                    "data",
                    "created_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "feature": {
                        "type": "string",
                        "enum": [
                            "ai_reputation",
                            "competitor"
                        ]
                    },
                    "kind": {
                        "description": "ai_reputation: sentiment_drop, stopped_mentioning, wrong_entity, rating_inaccurate, new_complaint, new_review_site, new_alternative; competitor: entered_top, rating_overtook, velocity_overtook, grade_passed.",
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "detail": {
                        "type": "string",
                        "nullable": true
                    },
                    "data": {
                        "description": "Kind-specific fields (engine, competitor, figures).",
                        "type": "object"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "V1AppReviewPage": {
                "description": "One enabled review page with the public facts of its `info.json`.",
                "required": [
                    "uuid",
                    "is_default",
                    "name",
                    "review_url",
                    "counter_url",
                    "look",
                    "accent",
                    "on_accent",
                    "line",
                    "theme",
                    "logo_url",
                    "sample"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "is_default": {
                        "type": "boolean"
                    },
                    "name": {
                        "description": "The name the page shows (display name, else the company name).",
                        "type": "string"
                    },
                    "review_url": {
                        "description": "The public page URL.",
                        "type": "string"
                    },
                    "counter_url": {
                        "description": "The counter screen URL.",
                        "type": "string"
                    },
                    "look": {
                        "description": "`grades`: no accent of the business's own (the Grades.com look); `accent`: its accent as the ground.",
                        "type": "string",
                        "enum": [
                            "grades",
                            "accent"
                        ]
                    },
                    "accent": {
                        "description": "The accent the page uses (after the contrast check).",
                        "type": "string"
                    },
                    "on_accent": {
                        "description": "Text color on the accent.",
                        "type": "string"
                    },
                    "line": {
                        "description": "The owner's headline, else \"Scan to review us on <Site>\" while the page goes straight to one site.",
                        "type": "string"
                    },
                    "theme": {
                        "type": "string",
                        "enum": [
                            "light",
                            "dark"
                        ]
                    },
                    "logo_url": {
                        "description": "The company logo; null when none is shown.",
                        "type": "string",
                        "nullable": true
                    },
                    "sample": {
                        "description": "true for a demo business (sample page).",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1AppReviewPagesBusiness": {
                "required": [
                    "company",
                    "pages"
                ],
                "properties": {
                    "company": {
                        "required": [
                            "uuid",
                            "name"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string",
                                "example": "Wrenfield Dental Studio"
                            }
                        },
                        "type": "object"
                    },
                    "pages": {
                        "description": "Enabled pages, the default first, then by name.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AppReviewPage"
                        }
                    }
                },
                "type": "object"
            },
            "V1BigQueryExport": {
                "properties": {
                    "available": {
                        "description": "False: BigQuery exports are switched off.",
                        "type": "boolean"
                    },
                    "configured": {
                        "type": "boolean"
                    },
                    "service_account": {
                        "description": "Grant it roles/bigquery.dataEditor on the dataset.",
                        "type": "string"
                    },
                    "role": {
                        "type": "string"
                    },
                    "cadences": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "daily",
                                "hourly"
                            ]
                        }
                    },
                    "plan_allows": {
                        "type": "boolean"
                    },
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "project_id": {
                        "type": "string"
                    },
                    "dataset_id": {
                        "type": "string"
                    },
                    "table_prefix": {
                        "type": "string"
                    },
                    "tables": {
                        "type": "object"
                    },
                    "location": {
                        "type": "string",
                        "nullable": true
                    },
                    "include_versions": {
                        "type": "boolean"
                    },
                    "all_locations": {
                        "type": "boolean"
                    },
                    "cadence": {
                        "type": "string",
                        "enum": [
                            "daily",
                            "hourly"
                        ]
                    },
                    "effective_cadence": {
                        "type": "string",
                        "enum": [
                            "daily",
                            "hourly"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "active",
                            "failed"
                        ]
                    },
                    "tested_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_synced_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_success_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "next_sync_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "sync_requested": {
                        "type": "boolean"
                    },
                    "failure_count": {
                        "type": "integer"
                    },
                    "last_sync_status": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "ok",
                            "failed"
                        ]
                    },
                    "last_error": {
                        "description": "A plain sentence saying what failed and what to do (never BigQuery's own text).",
                        "type": "string",
                        "nullable": true
                    },
                    "last_error_code": {
                        "type": "string",
                        "example": "access_denied",
                        "nullable": true
                    },
                    "last_error_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "iam": {
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1BrowserConnectMeta": {
                "description": "How connecting works now: availability, the sign-in methods, the connect service's WebSocket URL, the worker's public key for shared sign-in details (null when none), the link lifetime.",
                "required": [
                    "available",
                    "methods",
                    "ws_url",
                    "credentials_key",
                    "link_ttl_seconds"
                ],
                "properties": {
                    "available": {
                        "type": "boolean"
                    },
                    "methods": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "live",
                                "credentials"
                            ]
                        }
                    },
                    "ws_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "credentials_key": {
                        "required": [
                            "kid",
                            "alg",
                            "spki"
                        ],
                        "properties": {
                            "kid": {
                                "type": "string"
                            },
                            "alg": {
                                "type": "string"
                            },
                            "spki": {
                                "description": "Base64 SPKI DER of the RSA public key.",
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "link_ttl_seconds": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1BrowserConnectSite": {
                "description": "A site that can be connected, with the texts to accept per sign-in method.",
                "required": [
                    "site",
                    "label",
                    "kinds",
                    "consent_text",
                    "consent_texts",
                    "policy_note",
                    "recommended_method"
                ],
                "properties": {
                    "site": {
                        "type": "string",
                        "example": "yelp"
                    },
                    "label": {
                        "type": "string"
                    },
                    "kinds": {
                        "description": "The browser job kinds the site supports.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "reply",
                                "report_review",
                                "login_check"
                            ]
                        }
                    },
                    "consent_text": {
                        "description": "The text for the `live` method.",
                        "type": "string"
                    },
                    "consent_texts": {
                        "description": "The consent text per sign-in method (keys: the methods).",
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    },
                    "policy_note": {
                        "type": "string"
                    },
                    "recommended_method": {
                        "type": "string",
                        "enum": [
                            "live",
                            "credentials"
                        ]
                    }
                },
                "type": "object"
            },
            "V1BrowserSessionListMeta": {
                "required": [
                    "enabled",
                    "worker_available",
                    "plan_allows",
                    "connect",
                    "sites",
                    "consent_version",
                    "reporting"
                ],
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "worker_available": {
                        "type": "boolean"
                    },
                    "plan_allows": {
                        "type": "boolean"
                    },
                    "connect": {
                        "$ref": "#/components/schemas/V1BrowserConnectMeta"
                    },
                    "sites": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1BrowserConnectSite"
                        }
                    },
                    "consent_version": {
                        "type": "string"
                    },
                    "reporting": {
                        "required": [
                            "notice",
                            "platform_sites"
                        ],
                        "properties": {
                            "notice": {
                                "type": "string"
                            },
                            "platform_sites": {
                                "type": "array",
                                "items": {
                                    "required": [
                                        "site",
                                        "label",
                                        "available"
                                    ],
                                    "properties": {
                                        "site": {
                                            "type": "string",
                                            "example": "google"
                                        },
                                        "label": {
                                            "type": "string"
                                        },
                                        "available": {
                                            "description": "Whether grades.com's own account files reports on this site now.",
                                            "type": "boolean"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1BrowserConnectStartMeta": {
                "description": "The connect attempt just opened: `connect_url` for `live` (token in the URL fragment), `connect_token` + `ws_url` for `credentials`.",
                "required": [
                    "attempt",
                    "connect_url",
                    "connect_token",
                    "ws_url",
                    "connect_expires_at"
                ],
                "properties": {
                    "attempt": {
                        "$ref": "#/components/schemas/V1BrowserConnectAttempt"
                    },
                    "connect_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "connect_token": {
                        "type": "string",
                        "nullable": true
                    },
                    "ws_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "connect_expires_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "V1BrowserConnectRequest": {
                "required": [
                    "site",
                    "consent",
                    "consent_version"
                ],
                "properties": {
                    "site": {
                        "description": "A site from `meta.sites` of the list.",
                        "type": "string"
                    },
                    "method": {
                        "type": "string",
                        "default": "live",
                        "enum": [
                            "live",
                            "credentials"
                        ]
                    },
                    "consent": {
                        "description": "Must be accepted (true).",
                        "type": "boolean"
                    },
                    "consent_version": {
                        "description": "The current `meta.consent_version`.",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1BrowserJobEvidence": {
                "required": [
                    "job",
                    "evidence"
                ],
                "properties": {
                    "job": {
                        "required": [
                            "uuid",
                            "kind",
                            "site",
                            "status",
                            "error_code",
                            "completed_at"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "kind": {
                                "type": "string",
                                "enum": [
                                    "reply",
                                    "report_review",
                                    "login_check"
                                ]
                            },
                            "site": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "queued",
                                    "claimed",
                                    "succeeded",
                                    "failed",
                                    "needs_owner",
                                    "canceled",
                                    "rehearsed"
                                ]
                            },
                            "error_code": {
                                "type": "string",
                                "nullable": true
                            },
                            "completed_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "evidence": {
                        "type": "array",
                        "items": {
                            "required": [
                                "kind",
                                "content_type",
                                "bytes",
                                "sha256",
                                "attempt",
                                "captured_at",
                                "expired",
                                "url",
                                "url_expires_at"
                            ],
                            "properties": {
                                "kind": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                        "before",
                                        "after",
                                        "html",
                                        "error",
                                        "rehearsal"
                                    ]
                                },
                                "content_type": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "bytes": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "sha256": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "attempt": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "captured_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "expired": {
                                    "description": "Older than the retention: no link.",
                                    "type": "boolean"
                                },
                                "url": {
                                    "description": "Signed download link (10 minutes); null when storage is not configured or the evidence expired.",
                                    "type": "string",
                                    "nullable": true
                                },
                                "url_expires_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1BrowserEvidenceEntry": {
                "description": "One uploaded piece of evidence (an object under the job's prefix, named by the evidence call).",
                "required": [
                    "kind",
                    "object_name",
                    "content_type",
                    "bytes",
                    "sha256"
                ],
                "properties": {
                    "kind": {
                        "type": "string",
                        "enum": [
                            "before",
                            "after",
                            "html",
                            "error",
                            "rehearsal"
                        ]
                    },
                    "object_name": {
                        "type": "string",
                        "maxLength": 512
                    },
                    "content_type": {
                        "type": "string",
                        "enum": [
                            "image/png",
                            "image/jpeg",
                            "text/html",
                            "application/json"
                        ]
                    },
                    "bytes": {
                        "type": "integer",
                        "maximum": 5242880,
                        "minimum": 0
                    },
                    "sha256": {
                        "type": "string",
                        "pattern": "^[a-f0-9]{64}$"
                    }
                },
                "type": "object"
            },
            "V1BrowserJobStatus": {
                "required": [
                    "uuid",
                    "status"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "queued",
                            "claimed",
                            "succeeded",
                            "failed",
                            "needs_owner",
                            "canceled",
                            "rehearsed"
                        ]
                    }
                },
                "type": "object"
            },
            "V1CelebrationFiles": {
                "description": "One URL per file type (mp4, gif, png).",
                "properties": {
                    "mp4": {
                        "type": "string",
                        "nullable": true
                    },
                    "gif": {
                        "type": "string",
                        "nullable": true
                    },
                    "png": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1CelebrationVariant": {
                "properties": {
                    "look": {
                        "type": "string",
                        "enum": [
                            "dark",
                            "light"
                        ]
                    },
                    "format": {
                        "type": "string",
                        "enum": [
                            "square",
                            "story",
                            "landscape"
                        ]
                    },
                    "width": {
                        "type": "integer"
                    },
                    "height": {
                        "type": "integer"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "ready",
                            "queued",
                            "failed",
                            "none"
                        ]
                    },
                    "ready": {
                        "type": "boolean"
                    },
                    "rendered_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "files": {
                        "$ref": "#/components/schemas/V1CelebrationFiles"
                    },
                    "links": {
                        "$ref": "#/components/schemas/V1CelebrationFiles"
                    },
                    "preview_url": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1CelebrationItem": {
                "properties": {
                    "key": {
                        "type": "string"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "milestone",
                            "award",
                            "best",
                            "above_beyond",
                            "grade"
                        ]
                    },
                    "template": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "earned_at": {
                        "type": "string",
                        "nullable": true
                    },
                    "captions": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "hashtags": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "profile_url": {
                        "type": "string"
                    },
                    "variants": {
                        "description": "Six variants: look dark | light x format square | story | landscape.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1CelebrationVariant"
                        }
                    },
                    "publications": {
                        "description": "Google posts of the item, newest first (list only; not on the render response).",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1CelebrationPublication"
                        }
                    }
                },
                "type": "object"
            },
            "V1CelebrationPublication": {
                "description": "One attempt to post a celebration on a channel (insert-only; a removal is its own row).",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "channel": {
                        "type": "string",
                        "enum": [
                            "google"
                        ]
                    },
                    "item_key": {
                        "type": "string"
                    },
                    "state": {
                        "type": "string",
                        "enum": [
                            "created",
                            "failed",
                            "deleted"
                        ]
                    },
                    "trigger": {
                        "type": "string",
                        "enum": [
                            "manual",
                            "auto"
                        ]
                    },
                    "external_name": {
                        "description": "Google local post resource name.",
                        "type": "string",
                        "nullable": true
                    },
                    "external_state": {
                        "type": "string",
                        "nullable": true
                    },
                    "search_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "caption": {
                        "type": "string",
                        "nullable": true
                    },
                    "image_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "cta_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "look": {
                        "type": "string",
                        "nullable": true
                    },
                    "error": {
                        "type": "string",
                        "nullable": true
                    },
                    "published_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1CelebrationSettings": {
                "properties": {
                    "auto_post_google": {
                        "type": "boolean"
                    },
                    "google": {
                        "properties": {
                            "enabled": {
                                "description": "Whether Post to Google is switched on platform-wide.",
                                "type": "boolean"
                            },
                            "connected": {
                                "type": "boolean"
                            },
                            "needs_reconnect": {
                                "type": "boolean"
                            },
                            "connect_url": {
                                "type": "string"
                            },
                            "look": {
                                "description": "Default look of a Google post.",
                                "type": "string",
                                "enum": [
                                    "dark",
                                    "light"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "min_days_between": {
                        "description": "Days between automatic Google posts.",
                        "type": "integer"
                    },
                    "next_auto_post_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ChatHook": {
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "slack",
                            "teams",
                            "google_chat"
                        ]
                    },
                    "name": {
                        "type": "string"
                    },
                    "url_hint": {
                        "description": "Host and the last characters of the webhook URL (the URL is never returned).",
                        "type": "string"
                    },
                    "events": {
                        "description": "The events it sends (with rules: every rule's events).",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "rules": {
                        "description": "Routing rules; null = every event of `events` for this company.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ChatHookRule"
                        },
                        "nullable": true
                    },
                    "weekly_digest": {
                        "description": "Posts a weekly summary on Monday at 08:00 local time.",
                        "type": "boolean"
                    },
                    "active": {
                        "type": "boolean"
                    },
                    "status": {
                        "description": "disconnected = the chat app said the webhook is gone (add it again; nothing is sent), failed = switched off after 5 failures in a row, paused = switched off by a person, active.",
                        "type": "string",
                        "enum": [
                            "active",
                            "paused",
                            "failed",
                            "disconnected"
                        ]
                    },
                    "failed_at": {
                        "description": "Set when failures switched it off: 5 refusals in a row, or no answer for 3 days (10 tries).",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "failure_count": {
                        "type": "integer"
                    },
                    "last_sent_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_error": {
                        "type": "string",
                        "nullable": true
                    },
                    "disconnected_at": {
                        "description": "When the chat app answered that the webhook is gone.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "disconnect_reason": {
                        "description": "The app's answer: no_service, channel_not_found, invalid_token, token_revoked, http_404, http_410 ...",
                        "type": "string",
                        "nullable": true
                    },
                    "disconnected_message": {
                        "description": "For the dashboard, e.g. \"Disconnected in Slack: add it again.\"",
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ChatHookRule": {
                "description": "One routing rule: an event is sent when any rule matches it (once). Review filters apply to review.created, review.removed and recovery.case.opened; a rule with a review filter never matches other events.",
                "properties": {
                    "events": {
                        "description": "Default [\"review.created\"].",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "min_rating": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 5,
                        "minimum": 1
                    },
                    "max_rating": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 5,
                        "minimum": 1
                    },
                    "sites": {
                        "description": "Site keys; \"google\" also matches google_maps etc.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "locations": {
                        "description": "Company uuids: this business and, on an HQ, its locations. Empty = this business only.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uuid"
                        }
                    },
                    "languages": {
                        "description": "en, es, fr, pt, de, it (a review whose language is unclear never matches).",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "has_text": {
                        "type": "boolean",
                        "nullable": true
                    },
                    "keywords": {
                        "description": "Any of them, case-insensitive, in the review text (at most 20).",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "type": "object"
            },
            "V1CompanyAgency": {
                "description": "The agency side of a business: its agency (or null), its plan there, the grace period after leaving, and the pending requests of agencies (only for the business's own admins, else empty).",
                "required": [
                    "company",
                    "agency",
                    "plan",
                    "joined_at",
                    "grace",
                    "requests"
                ],
                "properties": {
                    "company": {
                        "$ref": "#/components/schemas/V1AgencyCompanyRef"
                    },
                    "agency": {
                        "required": [
                            "uuid",
                            "slug",
                            "name"
                        ],
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "slug": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "plan": {
                        "description": "The agency plan; null without an agency.",
                        "type": "string",
                        "nullable": true
                    },
                    "joined_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "grace": {
                        "description": "After leaving an agency: the agency plan is kept until `until`; null otherwise.",
                        "required": [
                            "until",
                            "plan"
                        ],
                        "properties": {
                            "until": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "plan": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "requests": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AgencyClientRequest"
                        }
                    }
                },
                "type": "object"
            },
            "V1CompanyInput": {
                "description": "Company fields for create (POST, `name` required) and update (PATCH, any subset).",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "Dr. Alex Rubinov",
                        "maxLength": 250
                    },
                    "website": {
                        "description": "A bare domain gets `https://`.",
                        "type": "string",
                        "example": "https://dralex.nyc",
                        "nullable": true
                    },
                    "phone": {
                        "description": "US phone number.",
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "nullable": true
                    },
                    "address": {
                        "properties": {
                            "line1": {
                                "type": "string",
                                "nullable": true
                            },
                            "line2": {
                                "type": "string",
                                "nullable": true
                            },
                            "city": {
                                "type": "string",
                                "nullable": true
                            },
                            "state": {
                                "type": "string",
                                "nullable": true
                            },
                            "zip": {
                                "type": "string",
                                "nullable": true
                            },
                            "country": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "timezone": {
                        "type": "string",
                        "example": "America/New_York",
                        "nullable": true
                    },
                    "hq_company": {
                        "description": "Uuid of the HQ to bill this location under as an extra location; `null` on PATCH detaches.",
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "location_nickname": {
                        "type": "string",
                        "example": "Midtown",
                        "nullable": true
                    },
                    "auto_connect_sources": {
                        "description": "Let the review radar and source discovery connect profiles on verified customer-review sites by themselves (docs/review-radar.md \"Auto-connect\").",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1CompetitorMetrics": {
                "description": "Compare figures; null where we hold no value.",
                "required": [
                    "grade",
                    "rating",
                    "review_count",
                    "reviews_12m",
                    "response_rate",
                    "ai_mention_share"
                ],
                "properties": {
                    "grade": {
                        "type": "string",
                        "nullable": true
                    },
                    "rating": {
                        "type": "number",
                        "nullable": true
                    },
                    "review_count": {
                        "type": "integer",
                        "nullable": true
                    },
                    "reviews_12m": {
                        "type": "integer",
                        "nullable": true
                    },
                    "response_rate": {
                        "type": "number",
                        "nullable": true
                    },
                    "ai_mention_share": {
                        "type": "number",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1CompetitorReciprocal": {
                "description": "The competitor's own public edge names the subject; null when it does not.",
                "required": [
                    "mentions",
                    "engines",
                    "co_mentions"
                ],
                "properties": {
                    "mentions": {
                        "type": "integer"
                    },
                    "engines": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "co_mentions": {
                        "type": "integer"
                    }
                },
                "type": "object",
                "nullable": true
            },
            "V1Competitor": {
                "required": [
                    "competitor",
                    "score",
                    "signals",
                    "reciprocal",
                    "metrics",
                    "evidence",
                    "first_seen",
                    "last_seen",
                    "history",
                    "why",
                    "key"
                ],
                "properties": {
                    "competitor": {
                        "required": [
                            "type",
                            "id",
                            "name",
                            "domain",
                            "city",
                            "state",
                            "lat",
                            "lng",
                            "profile_url"
                        ],
                        "properties": {
                            "type": {
                                "type": "string",
                                "enum": [
                                    "listing",
                                    "brand",
                                    "external"
                                ]
                            },
                            "id": {
                                "description": "Listing or brand id.",
                                "type": "integer",
                                "nullable": true
                            },
                            "name": {
                                "type": "string"
                            },
                            "domain": {
                                "type": "string",
                                "nullable": true
                            },
                            "city": {
                                "type": "string",
                                "nullable": true
                            },
                            "state": {
                                "type": "string",
                                "nullable": true
                            },
                            "lat": {
                                "type": "number",
                                "nullable": true
                            },
                            "lng": {
                                "type": "number",
                                "nullable": true
                            },
                            "profile_url": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "score": {
                        "description": "0-1",
                        "type": "number"
                    },
                    "signals": {
                        "required": [
                            "ai_alternatives",
                            "ai_co_mentions",
                            "directory_peer",
                            "website_similarity",
                            "hub",
                            "reciprocal"
                        ],
                        "properties": {
                            "ai_alternatives": {
                                "required": [
                                    "mentions",
                                    "engines"
                                ],
                                "properties": {
                                    "mentions": {
                                        "type": "integer"
                                    },
                                    "engines": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "type": "object"
                            },
                            "ai_co_mentions": {
                                "type": "integer"
                            },
                            "directory_peer": {
                                "required": [
                                    "same_category",
                                    "distance_km"
                                ],
                                "properties": {
                                    "same_category": {
                                        "type": "boolean"
                                    },
                                    "distance_km": {
                                        "type": "number",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            },
                            "website_similarity": {
                                "type": "number",
                                "nullable": true
                            },
                            "hub": {
                                "required": [
                                    "sources"
                                ],
                                "properties": {
                                    "sources": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "type": "object"
                            },
                            "reciprocal": {
                                "$ref": "#/components/schemas/V1CompetitorReciprocal"
                            }
                        },
                        "type": "object"
                    },
                    "reciprocal": {
                        "description": "A competitor only because its own public edge names the subject.",
                        "type": "boolean"
                    },
                    "metrics": {
                        "$ref": "#/components/schemas/V1CompetitorMetrics"
                    },
                    "evidence": {
                        "type": "array",
                        "items": {
                            "required": [
                                "type",
                                "label",
                                "at",
                                "url"
                            ],
                            "properties": {
                                "type": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "at": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "url": {
                                    "type": "string",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "first_seen": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_seen": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "history": {
                        "description": "Its monthly snapshots.",
                        "required": [
                            "months_seen",
                            "first_month",
                            "last_month",
                            "by_month",
                            "new_this_month"
                        ],
                        "properties": {
                            "months_seen": {
                                "type": "integer"
                            },
                            "first_month": {
                                "type": "string",
                                "nullable": true
                            },
                            "last_month": {
                                "type": "string",
                                "nullable": true
                            },
                            "by_month": {
                                "type": "array",
                                "items": {
                                    "required": [
                                        "month",
                                        "score",
                                        "rank"
                                    ],
                                    "properties": {
                                        "month": {
                                            "type": "string"
                                        },
                                        "score": {
                                            "type": "number"
                                        },
                                        "rank": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "new_this_month": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "why": {
                        "description": "Why it is a competitor, in words.",
                        "type": "string",
                        "nullable": true
                    },
                    "key": {
                        "description": "l:<listing>, b:<brand>, d:<domain> or n:<name>.",
                        "type": "string"
                    },
                    "location_ids": {
                        "description": "HQ view only: uuids of the locations it competes with.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uuid"
                        }
                    }
                },
                "type": "object"
            },
            "V1CompetitorReportMeta": {
                "required": [
                    "subject",
                    "generated_at",
                    "signals_available",
                    "history",
                    "matrix",
                    "attributes"
                ],
                "properties": {
                    "subject": {
                        "required": [
                            "name",
                            "lat",
                            "lng",
                            "metrics"
                        ],
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "lat": {
                                "type": "number",
                                "nullable": true
                            },
                            "lng": {
                                "type": "number",
                                "nullable": true
                            },
                            "metrics": {
                                "$ref": "#/components/schemas/V1CompetitorMetrics"
                            }
                        },
                        "type": "object"
                    },
                    "generated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "signals_available": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "history": {
                        "required": [
                            "months",
                            "current_month",
                            "compared_to",
                            "new_count",
                            "gone"
                        ],
                        "properties": {
                            "months": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "current_month": {
                                "type": "string"
                            },
                            "compared_to": {
                                "type": "string",
                                "nullable": true
                            },
                            "new_count": {
                                "type": "integer"
                            },
                            "gone": {
                                "description": "Competitors of the compared month that are no longer in the set.",
                                "type": "array",
                                "items": {
                                    "required": [
                                        "competitor",
                                        "last_month",
                                        "last_score",
                                        "last_rank"
                                    ],
                                    "properties": {
                                        "competitor": {
                                            "properties": {
                                                "type": {
                                                    "type": "string"
                                                },
                                                "id": {
                                                    "type": "integer",
                                                    "nullable": true
                                                },
                                                "name": {
                                                    "type": "string"
                                                },
                                                "domain": {
                                                    "type": "string",
                                                    "nullable": true
                                                }
                                            },
                                            "type": "object"
                                        },
                                        "last_month": {
                                            "type": "string"
                                        },
                                        "last_score": {
                                            "type": "number"
                                        },
                                        "last_rank": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "matrix": {
                        "description": "The leaders matrix of the subject and the competitors shown (docs/competitors.md \"Leaders matrix\"); null when too few have review data.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "attributes": {
                        "description": "Attribute comparison with the competitor set and the subject's attribute badges (docs/directory.md \"Attribute badges\"); null without a listing.",
                        "properties": {
                            "comparison": {
                                "type": "object",
                                "nullable": true,
                                "additionalProperties": true
                            },
                            "badges": {
                                "type": "object",
                                "additionalProperties": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1CompetitorSide": {
                "required": [
                    "key",
                    "type",
                    "name",
                    "listing_id",
                    "profile_url",
                    "logo_url",
                    "score",
                    "grade",
                    "as_of",
                    "sites",
                    "known_for"
                ],
                "properties": {
                    "key": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "listing_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "profile_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "logo_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "score": {
                        "type": "number",
                        "nullable": true
                    },
                    "grade": {
                        "type": "string",
                        "nullable": true
                    },
                    "as_of": {
                        "type": "string",
                        "nullable": true
                    },
                    "sites": {
                        "description": "Rating and count per review site, each with its own date.",
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "known_for": {
                        "description": "What its public profile says it is known for: `available`, `reason`, `praise` and `complaints` (theme labels, summaries, counts; no quotes), `basis`.",
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "reason": {
                                "type": "string",
                                "nullable": true
                            },
                            "praise": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "complaints": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "basis": {
                                "type": "object",
                                "nullable": true,
                                "additionalProperties": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1CompetitorHeadToHead": {
                "required": [
                    "against",
                    "you",
                    "them",
                    "compared_to",
                    "rows",
                    "options"
                ],
                "properties": {
                    "against": {
                        "description": "The competitor key compared with.",
                        "type": "string"
                    },
                    "you": {
                        "$ref": "#/components/schemas/V1CompetitorSide"
                    },
                    "them": {
                        "$ref": "#/components/schemas/V1CompetitorSide"
                    },
                    "compared_to": {
                        "description": "The previous month (Y-m).",
                        "type": "string"
                    },
                    "rows": {
                        "type": "array",
                        "items": {
                            "required": [
                                "key",
                                "label",
                                "unit",
                                "you",
                                "them",
                                "delta_you",
                                "delta_them",
                                "better",
                                "you_detail",
                                "them_detail"
                            ],
                            "properties": {
                                "key": {
                                    "type": "string",
                                    "enum": [
                                        "score",
                                        "rating",
                                        "reviews",
                                        "reviews_12m",
                                        "response_rate",
                                        "ai_sentiment",
                                        "ai_mentioned"
                                    ]
                                },
                                "label": {
                                    "type": "string"
                                },
                                "unit": {
                                    "type": "string"
                                },
                                "you": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "them": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "delta_you": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "delta_them": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "better": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                        "you",
                                        "them",
                                        "tie"
                                    ]
                                },
                                "you_detail": {
                                    "description": "`score`: `{grade}`; `ai_sentiment`: the sentiment counts; else null.",
                                    "type": "object",
                                    "nullable": true,
                                    "additionalProperties": true
                                },
                                "them_detail": {
                                    "type": "object",
                                    "nullable": true,
                                    "additionalProperties": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "options": {
                        "description": "The competitors to pick from, strongest first.",
                        "type": "array",
                        "items": {
                            "required": [
                                "key",
                                "name",
                                "type"
                            ],
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "type": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1CompetitorPin": {
                "required": [
                    "key",
                    "name"
                ],
                "properties": {
                    "key": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "lat": {
                        "type": "number",
                        "nullable": true
                    },
                    "lng": {
                        "type": "number",
                        "nullable": true
                    },
                    "score": {
                        "type": "number",
                        "nullable": true
                    },
                    "grade": {
                        "type": "string",
                        "nullable": true
                    },
                    "rating": {
                        "type": "number",
                        "nullable": true
                    },
                    "reviews": {
                        "type": "integer"
                    },
                    "distance_km": {
                        "type": "number",
                        "nullable": true
                    },
                    "profile_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "logo_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "in_set": {
                        "description": "`points` only: in the competitor set its profile compares.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1CompetitorMap": {
                "required": [
                    "center",
                    "you",
                    "points",
                    "unplotted",
                    "set_size"
                ],
                "properties": {
                    "center": {
                        "required": [
                            "lat",
                            "lng"
                        ],
                        "properties": {
                            "lat": {
                                "type": "number"
                            },
                            "lng": {
                                "type": "number"
                            }
                        },
                        "type": "object"
                    },
                    "you": {
                        "$ref": "#/components/schemas/V1CompetitorPin"
                    },
                    "points": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1CompetitorPin"
                        }
                    },
                    "unplotted": {
                        "type": "array",
                        "items": {
                            "required": [
                                "key",
                                "name",
                                "reason"
                            ],
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "reason": {
                                    "type": "string",
                                    "enum": [
                                        "no_location",
                                        "not_listed",
                                        "map_full"
                                    ]
                                }
                            },
                            "type": "object"
                        }
                    },
                    "set_size": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1LocationCompetitorRank": {
                "required": [
                    "company",
                    "name",
                    "listing",
                    "city",
                    "state",
                    "profile_url",
                    "scope",
                    "rank",
                    "of",
                    "score",
                    "grade",
                    "above",
                    "below_count",
                    "rank_last_month",
                    "trend",
                    "reason"
                ],
                "properties": {
                    "company": {
                        "description": "The location's uuid.",
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "listing": {
                        "description": "Directory listing id.",
                        "type": "integer",
                        "nullable": true
                    },
                    "city": {
                        "type": "string",
                        "nullable": true
                    },
                    "state": {
                        "type": "string",
                        "nullable": true
                    },
                    "profile_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "scope": {
                        "description": "Scope of the competitor set.",
                        "type": "string",
                        "nullable": true
                    },
                    "rank": {
                        "type": "integer",
                        "nullable": true
                    },
                    "of": {
                        "type": "integer",
                        "nullable": true
                    },
                    "score": {
                        "type": "number",
                        "nullable": true
                    },
                    "grade": {
                        "type": "string",
                        "nullable": true
                    },
                    "above": {
                        "description": "The businesses ahead of it.",
                        "type": "array",
                        "items": {
                            "required": [
                                "listing",
                                "name",
                                "score",
                                "grade",
                                "profile_url"
                            ],
                            "properties": {
                                "listing": {
                                    "type": "integer"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "score": {
                                    "type": "number"
                                },
                                "grade": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "profile_url": {
                                    "type": "string",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "below_count": {
                        "type": "integer",
                        "nullable": true
                    },
                    "rank_last_month": {
                        "type": "integer",
                        "nullable": true
                    },
                    "trend": {
                        "description": "Positive = moved up.",
                        "type": "integer",
                        "nullable": true
                    },
                    "reason": {
                        "description": "Why `rank` is null.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "no_listing",
                            "no_set",
                            "no_score"
                        ]
                    }
                },
                "type": "object"
            },
            "V1DirectReviewSettings": {
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "mode": {
                        "description": "`public` (every verified review is published and counts), `curated` (the business features reviews, labeled \"Selected by the business\", never counted) or `private` (dashboard only, never published).",
                        "type": "string",
                        "enum": [
                            "public",
                            "curated",
                            "private"
                        ]
                    },
                    "text": {
                        "type": "string",
                        "enum": [
                            "required",
                            "optional",
                            "off"
                        ]
                    },
                    "photos": {
                        "type": "boolean"
                    },
                    "video": {
                        "type": "string",
                        "enum": [
                            "off",
                            "optional",
                            "required"
                        ]
                    },
                    "intro": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 500
                    }
                },
                "type": "object"
            },
            "V1DirectReviewSettingsView": {
                "description": "The settings as read back: the stored fields plus the form and list URLs, the mode wording, limits and counts.",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1DirectReviewSettings"
                    },
                    {
                        "properties": {
                            "form_url": {
                                "type": "string"
                            },
                            "reviews_url": {
                                "type": "string"
                            },
                            "notice": {
                                "description": "What the form tells the reviewer under the mode.",
                                "type": "string"
                            },
                            "consent": {
                                "description": "The consent box text under the mode.",
                                "type": "string"
                            },
                            "modes": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "value": {
                                            "type": "string",
                                            "enum": [
                                                "public",
                                                "curated",
                                                "private"
                                            ]
                                        },
                                        "label": {
                                            "type": "string"
                                        },
                                        "description": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "limits": {
                                "properties": {
                                    "photos_max": {
                                        "type": "integer"
                                    },
                                    "photo_max_mb": {
                                        "type": "integer"
                                    },
                                    "video_max_seconds": {
                                        "type": "integer"
                                    },
                                    "video_max_mb": {
                                        "type": "integer"
                                    },
                                    "text_max": {
                                        "type": "integer"
                                    }
                                },
                                "type": "object"
                            },
                            "counts": {
                                "description": "Reviews by status.",
                                "properties": {
                                    "pending": {
                                        "type": "integer"
                                    },
                                    "published": {
                                        "type": "integer"
                                    },
                                    "received": {
                                        "type": "integer"
                                    },
                                    "featured": {
                                        "type": "integer"
                                    },
                                    "hidden": {
                                        "type": "integer"
                                    }
                                },
                                "type": "object"
                            },
                            "updated_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1DirectReviewMedia": {
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "photo",
                            "video"
                        ]
                    },
                    "url": {
                        "type": "string",
                        "nullable": true
                    },
                    "thumb_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "mime": {
                        "type": "string"
                    },
                    "width": {
                        "type": "integer",
                        "nullable": true
                    },
                    "height": {
                        "type": "integer",
                        "nullable": true
                    },
                    "duration_seconds": {
                        "type": "integer",
                        "nullable": true
                    },
                    "hidden": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1DirectReviewShare": {
                "description": "Whether the reviewer allowed sharing the video (share packages).",
                "properties": {
                    "allowed": {
                        "type": "boolean"
                    },
                    "withdrawn": {
                        "type": "boolean"
                    },
                    "consented_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "consent_version": {
                        "type": "string",
                        "nullable": true
                    },
                    "withdrawn_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "package_status": {
                        "description": "Status of the latest share package (only in the review state; null in share-package payloads).",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "queued",
                            "ready",
                            "failed",
                            "withdrawn"
                        ]
                    }
                },
                "type": "object"
            },
            "V1DirectReviewState": {
                "description": "The Grades.com state of a direct review.",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "review_id": {
                        "description": "Uuid of the review row.",
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "public",
                            "curated",
                            "private"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending_verification",
                            "published",
                            "received",
                            "hidden",
                            "expired"
                        ]
                    },
                    "featured": {
                        "type": "boolean"
                    },
                    "featured_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "shown": {
                        "description": "Shown publicly on Grades.com.",
                        "type": "boolean"
                    },
                    "counts": {
                        "description": "Counts in ratings and the grade.",
                        "type": "boolean"
                    },
                    "media": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1DirectReviewMedia"
                        }
                    },
                    "share": {
                        "$ref": "#/components/schemas/V1DirectReviewShare"
                    },
                    "history": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "event": {
                                    "type": "string"
                                },
                                "user_id": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "reason": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "at": {
                                    "type": "string",
                                    "format": "date-time"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1SharePackageReview": {
                "properties": {
                    "id": {
                        "description": "Uuid of the direct review.",
                        "type": "string",
                        "format": "uuid"
                    },
                    "review_id": {
                        "description": "Uuid of the review row.",
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "name": {
                        "description": "The reviewer's display name.",
                        "type": "string"
                    },
                    "rating": {
                        "type": "integer"
                    },
                    "published_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SharePackageFile": {
                "properties": {
                    "url": {
                        "description": "Public address, or a signed link for a private package.",
                        "type": "string",
                        "nullable": true
                    },
                    "bytes": {
                        "type": "integer"
                    },
                    "width": {
                        "type": "integer"
                    },
                    "height": {
                        "type": "integer"
                    },
                    "mime": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1SharePackage": {
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "queued",
                            "ready",
                            "failed",
                            "withdrawn"
                        ]
                    },
                    "requested_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "rendered_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "withdrawn_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "error": {
                        "description": "Only when `status` is failed.",
                        "type": "string",
                        "nullable": true
                    },
                    "consent_version": {
                        "type": "string"
                    },
                    "private": {
                        "description": "Signed, expiring links (healthcare businesses).",
                        "type": "boolean"
                    },
                    "files": {
                        "description": "Ready packages only: by kind (`vertical` MP4, `square` MP4, `cover` PNG); kinds not stored are left out.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": {
                            "$ref": "#/components/schemas/V1SharePackageFile"
                        }
                    },
                    "caption": {
                        "description": "Ready packages only: the caption texts (`title`, `description`, `hashtags`, `text`).",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "captions_from": {
                        "description": "Null in the 202 response that queued the package (stored as none until it is rendered).",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "review_text",
                            "transcript",
                            "none"
                        ]
                    },
                    "note": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SharePackageState": {
                "description": "One video review's share state and its latest package.",
                "properties": {
                    "review": {
                        "$ref": "#/components/schemas/V1SharePackageReview"
                    },
                    "share": {
                        "$ref": "#/components/schemas/V1DirectReviewShare"
                    },
                    "eligible": {
                        "type": "boolean"
                    },
                    "reason": {
                        "description": "Why no package may be made now; null when eligible.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "no_video",
                            "no_consent",
                            "withdrawn",
                            "not_published",
                            "video_hidden"
                        ]
                    },
                    "healthcare": {
                        "description": "Single review only.",
                        "type": "boolean"
                    },
                    "package": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1SharePackage"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "guidance": {
                        "description": "Single review only.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "limits": {
                        "description": "Single review only.",
                        "properties": {
                            "per_day": {
                                "type": "integer"
                            },
                            "used_today": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1EmailTriggerAddress": {
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "address": {
                        "description": "BCC or forward invoices / receipts here. Keep it private.",
                        "type": "string",
                        "example": "req-k3v9q0x2m7c4h8b1n5z6w2ta@in.grades.com"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "paused"
                        ]
                    },
                    "allowed_sender_domains": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "delay_minutes": {
                        "type": "integer",
                        "example": 2880
                    },
                    "daily_cap": {
                        "type": "integer",
                        "example": 200
                    },
                    "campaign": {
                        "type": "object",
                        "nullable": true
                    },
                    "location": {
                        "type": "object",
                        "nullable": true
                    },
                    "last_received_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "stats": {
                        "description": "Last 30 days.",
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1EmailTriggerEvent": {
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "outcome": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "accepted",
                            "existing",
                            "skipped"
                        ]
                    },
                    "reason": {
                        "type": "string",
                        "example": "recently_requested",
                        "nullable": true
                    },
                    "mode": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "bcc",
                            "forward"
                        ]
                    },
                    "customer": {
                        "description": "Masked: j***@e***.com",
                        "type": "string",
                        "nullable": true
                    },
                    "sender": {
                        "description": "Masked.",
                        "type": "string",
                        "nullable": true
                    },
                    "request_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "received_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1EmailTriggerSettings": {
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "paused"
                        ]
                    },
                    "allowed_sender_domains": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "nullable": true
                    },
                    "delay_days": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 30,
                        "minimum": 0
                    },
                    "delay_minutes": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 43200,
                        "minimum": 0
                    },
                    "daily_cap": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 1000,
                        "minimum": 1
                    },
                    "campaign": {
                        "description": "Campaign uuid or `default` (null = default).",
                        "type": "string",
                        "nullable": true
                    },
                    "location": {
                        "description": "Uuid of a location of this business (null = the business).",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewExport": {
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "sheets"
                        ]
                    },
                    "title": {
                        "type": "string"
                    },
                    "spreadsheet_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "spreadsheet_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "sync": {
                        "type": "string",
                        "enum": [
                            "none",
                            "hourly",
                            "daily"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "stopped",
                            "failed"
                        ]
                    },
                    "stop_reason": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "stopped_by_user",
                            "google_revoked",
                            "google_failed"
                        ]
                    },
                    "filters": {
                        "type": "object"
                    },
                    "columns": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "all_locations": {
                        "type": "boolean"
                    },
                    "include_versions": {
                        "description": "Earlier versions of reviews as extra rows.",
                        "type": "boolean"
                    },
                    "layout": {
                        "description": "null: the Reviews sheet only; `reporting`: also the Daily metrics and By platform tabs for reporting tools.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "reporting"
                        ]
                    },
                    "rows": {
                        "type": "integer",
                        "nullable": true
                    },
                    "last_synced_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "next_sync_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_error": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_by": {
                        "type": "object",
                        "nullable": true
                    },
                    "mine": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1ReviewFileExport": {
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "format": {
                        "type": "string",
                        "enum": [
                            "csv",
                            "xlsx"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "queued",
                            "building",
                            "ready",
                            "failed",
                            "expired"
                        ]
                    },
                    "rows": {
                        "type": "integer",
                        "nullable": true
                    },
                    "truncated": {
                        "type": "boolean"
                    },
                    "yelp_text_omitted": {
                        "type": "boolean"
                    },
                    "bytes": {
                        "type": "integer",
                        "nullable": true
                    },
                    "file_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "columns": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "all_locations": {
                        "type": "boolean"
                    },
                    "include_versions": {
                        "type": "boolean"
                    },
                    "error": {
                        "description": "`no_access`, `build_failed` or `timed_out` when failed.",
                        "type": "string",
                        "nullable": true
                    },
                    "expires_at": {
                        "description": "When the e-mailed link stops working.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "downloads": {
                        "type": "integer"
                    },
                    "emailed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "finished_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1GoogleGrant": {
                "properties": {
                    "connected": {
                        "type": "boolean"
                    },
                    "email": {
                        "type": "string",
                        "nullable": true
                    },
                    "connected_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "needs_reconnect": {
                        "type": "boolean"
                    },
                    "connect_url": {
                        "description": "Opened in a browser signed in to the dashboard (add `frontend_redirect_url`).",
                        "type": "string",
                        "format": "url"
                    },
                    "available": {
                        "description": "False: Google Sheets exports are switched off.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1ReviewExportFilters": {
                "description": "The review list's filters (all optional). Lists take an array or a comma-separated string.",
                "properties": {
                    "start_date": {
                        "type": "string",
                        "format": "date"
                    },
                    "end_date": {
                        "type": "string",
                        "format": "date"
                    },
                    "source_drivers": {
                        "description": "Review site keys (e.g. google, yelp_apify).",
                        "oneOf": [
                            {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            {
                                "type": "string"
                            }
                        ]
                    },
                    "min_rating": {
                        "type": "integer",
                        "maximum": 5,
                        "minimum": 1
                    },
                    "max_rating": {
                        "type": "integer",
                        "maximum": 5,
                        "minimum": 1
                    },
                    "has_company_response": {
                        "type": "boolean"
                    },
                    "min_length": {
                        "type": "integer",
                        "maximum": 65000,
                        "minimum": 0
                    },
                    "max_length": {
                        "type": "integer",
                        "maximum": 65000,
                        "minimum": 0
                    },
                    "s": {
                        "description": "Part of the review text or author name.",
                        "type": "string",
                        "maxLength": 200
                    },
                    "search": {
                        "description": "Alias of `s`.",
                        "type": "string",
                        "maxLength": 200
                    },
                    "removed": {
                        "description": "`exclude`: live reviews only, `only`: removed only; omitted: both.",
                        "type": "string",
                        "enum": [
                            "exclude",
                            "only"
                        ]
                    },
                    "tags": {
                        "description": "Review tag slugs (any of them).",
                        "oneOf": [
                            {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            {
                                "type": "string"
                            }
                        ]
                    },
                    "sentiment": {
                        "oneOf": [
                            {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            {
                                "type": "string"
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "V1ReviewExportRequest": {
                "description": "What to export. The filters go under `filters` or at the top level of the body.",
                "properties": {
                    "filters": {
                        "$ref": "#/components/schemas/V1ReviewExportFilters"
                    },
                    "columns": {
                        "description": "Column keys (see the CSV route); default: review_id and the default columns.",
                        "oneOf": [
                            {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            {
                                "type": "string"
                            }
                        ]
                    },
                    "all_locations": {
                        "description": "On an HQ: every location (needs access to all).",
                        "type": "boolean"
                    },
                    "include_versions": {
                        "description": "Earlier versions of reviews as extra rows.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1FeedbackReport": {
                "required": [
                    "reference",
                    "kind",
                    "origin",
                    "summary",
                    "status",
                    "created_at"
                ],
                "properties": {
                    "reference": {
                        "description": "Human reference, e.g. `FB-7K3Q2`.",
                        "type": "string"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "bug",
                            "wrong_answer",
                            "missing_feature",
                            "question",
                            "other"
                        ]
                    },
                    "origin": {
                        "type": "string",
                        "enum": [
                            "mcp",
                            "assistant",
                            "dashboard",
                            "api"
                        ]
                    },
                    "summary": {
                        "type": "string",
                        "maxLength": 200
                    },
                    "details": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "received",
                            "in_review",
                            "needs_info",
                            "planned",
                            "built",
                            "declined"
                        ]
                    },
                    "status_label": {
                        "type": "string",
                        "example": "Received"
                    },
                    "resolution": {
                        "description": "What was built or the answer, written by grades.com for the reporter.",
                        "type": "string",
                        "nullable": true
                    },
                    "resolved_release": {
                        "type": "string",
                        "example": "v3.41.0",
                        "nullable": true
                    },
                    "company": {
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "status_changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1FeedUrls": {
                "description": "The review feed addresses of a company.",
                "properties": {
                    "rss": {
                        "description": "RSS 2.0.",
                        "type": "string",
                        "format": "uri"
                    },
                    "atom": {
                        "description": "Atom 1.0.",
                        "type": "string",
                        "format": "uri"
                    },
                    "json": {
                        "description": "JSON Feed 1.1.",
                        "type": "string",
                        "format": "uri"
                    },
                    "summary": {
                        "description": "The rating summary JSON.",
                        "type": "string",
                        "format": "uri"
                    },
                    "placeholder": {
                        "description": "True when the addresses carry `gk_pub_YOUR_KEY`.",
                        "type": "boolean"
                    },
                    "all_locations": {
                        "description": "HQ only (absent otherwise): the same addresses with `all_locations=1`.",
                        "properties": {
                            "rss": {
                                "type": "string",
                                "format": "uri"
                            },
                            "atom": {
                                "type": "string",
                                "format": "uri"
                            },
                            "json": {
                                "type": "string",
                                "format": "uri"
                            },
                            "summary": {
                                "type": "string",
                                "format": "uri"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1InsightsTotals": {
                "required": [
                    "reviews",
                    "avg_rating",
                    "response_rate"
                ],
                "properties": {
                    "reviews": {
                        "type": "integer"
                    },
                    "avg_rating": {
                        "type": "number",
                        "nullable": true
                    },
                    "response_rate": {
                        "type": "number",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1InsightsPrevCounts": {
                "description": "The previous period's figures (null with `compare=none`).",
                "required": [
                    "reviews",
                    "avg",
                    "reply_rate"
                ],
                "properties": {
                    "reviews": {
                        "type": "integer"
                    },
                    "avg": {
                        "type": "number",
                        "nullable": true
                    },
                    "reply_rate": {
                        "type": "number",
                        "nullable": true
                    }
                },
                "type": "object",
                "nullable": true
            },
            "V1ReviewInsights": {
                "required": [
                    "period",
                    "volume",
                    "by_site",
                    "sentiment",
                    "response",
                    "themes",
                    "attributes",
                    "removed",
                    "locations",
                    "tags",
                    "highlights"
                ],
                "properties": {
                    "period": {
                        "required": [
                            "totals",
                            "previous"
                        ],
                        "properties": {
                            "totals": {
                                "$ref": "#/components/schemas/V1InsightsTotals"
                            },
                            "previous": {
                                "nullable": true,
                                "allOf": [
                                    {
                                        "$ref": "#/components/schemas/V1InsightsTotals"
                                    }
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "volume": {
                        "description": "Per month of the period.",
                        "type": "array",
                        "items": {
                            "required": [
                                "month",
                                "reviews",
                                "avg_rating",
                                "five_star_share"
                            ],
                            "properties": {
                                "month": {
                                    "type": "string",
                                    "example": "2026-10"
                                },
                                "reviews": {
                                    "type": "integer"
                                },
                                "avg_rating": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "five_star_share": {
                                    "type": "number",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "by_site": {
                        "description": "One row per review platform with reviews in the period or the previous one.",
                        "type": "array",
                        "items": {
                            "required": [
                                "site",
                                "platform",
                                "name",
                                "sources",
                                "reviews",
                                "avg",
                                "reply_rate",
                                "total",
                                "prev",
                                "trend"
                            ],
                            "properties": {
                                "site": {
                                    "type": "string"
                                },
                                "platform": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "sources": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "reviews": {
                                    "type": "integer"
                                },
                                "avg": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "reply_rate": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "total": {
                                    "type": "integer"
                                },
                                "prev": {
                                    "$ref": "#/components/schemas/V1InsightsPrevCounts"
                                },
                                "trend": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                        "up",
                                        "down",
                                        "flat"
                                    ]
                                }
                            },
                            "type": "object"
                        }
                    },
                    "sentiment": {
                        "required": [
                            "ai",
                            "reviews"
                        ],
                        "properties": {
                            "ai": {
                                "description": "AI answers per sentiment, per month with AI Reputation probes.",
                                "type": "array",
                                "items": {
                                    "required": [
                                        "month",
                                        "positive",
                                        "mixed",
                                        "negative"
                                    ],
                                    "properties": {
                                        "month": {
                                            "type": "string"
                                        },
                                        "positive": {
                                            "type": "integer"
                                        },
                                        "mixed": {
                                            "type": "integer"
                                        },
                                        "negative": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "reviews": {
                                "type": "array",
                                "items": {
                                    "required": [
                                        "month",
                                        "share_1_2_star",
                                        "rated"
                                    ],
                                    "properties": {
                                        "month": {
                                            "type": "string"
                                        },
                                        "share_1_2_star": {
                                            "type": "number",
                                            "nullable": true
                                        },
                                        "rated": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "response": {
                        "required": [
                            "rate",
                            "median_hours",
                            "replied",
                            "prev",
                            "trend"
                        ],
                        "properties": {
                            "rate": {
                                "type": "number",
                                "nullable": true
                            },
                            "median_hours": {
                                "type": "number",
                                "nullable": true
                            },
                            "replied": {
                                "type": "integer"
                            },
                            "prev": {
                                "properties": {
                                    "rate": {
                                        "type": "number",
                                        "nullable": true
                                    },
                                    "median_hours": {
                                        "type": "number",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            },
                            "trend": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "up",
                                    "down",
                                    "flat"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "themes": {
                        "required": [
                            "available",
                            "reason",
                            "praise",
                            "complaints",
                            "basis"
                        ],
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "reason": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "no_listing",
                                    "no_themes"
                                ]
                            },
                            "praise": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/V1InsightsTheme"
                                }
                            },
                            "complaints": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/V1InsightsTheme"
                                }
                            },
                            "basis": {
                                "properties": {
                                    "reviews": {
                                        "type": "integer"
                                    },
                                    "from": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "line": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "attributes": {
                        "description": "Attribute scores of the directory listings (empty without them).",
                        "type": "array",
                        "items": {
                            "required": [
                                "key",
                                "label",
                                "net",
                                "n",
                                "praise",
                                "complain",
                                "prev_net",
                                "pool_median",
                                "history"
                            ],
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "net": {
                                    "type": "number"
                                },
                                "n": {
                                    "type": "integer"
                                },
                                "praise": {
                                    "type": "integer"
                                },
                                "complain": {
                                    "type": "integer"
                                },
                                "prev_net": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "pool_median": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "history": {
                                    "type": "array",
                                    "items": {
                                        "required": [
                                            "month",
                                            "net"
                                        ],
                                        "properties": {
                                            "month": {
                                                "type": "string"
                                            },
                                            "net": {
                                                "type": "number"
                                            }
                                        },
                                        "type": "object"
                                    }
                                }
                            },
                            "type": "object"
                        }
                    },
                    "removed": {
                        "description": "Reviews removed from their site during the period.",
                        "required": [
                            "count",
                            "by_site"
                        ],
                        "properties": {
                            "count": {
                                "type": "integer"
                            },
                            "by_site": {
                                "type": "array",
                                "items": {
                                    "required": [
                                        "site",
                                        "platform",
                                        "name",
                                        "count"
                                    ],
                                    "properties": {
                                        "site": {
                                            "type": "string"
                                        },
                                        "platform": {
                                            "type": "string"
                                        },
                                        "name": {
                                            "type": "string"
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "locations": {
                        "description": "One row per location (an HQ with locations, for a caller who sees all of them); else null.",
                        "type": "array",
                        "items": {
                            "required": [
                                "company",
                                "name",
                                "nickname",
                                "is_hq",
                                "reviews",
                                "avg",
                                "reply_rate",
                                "total",
                                "avg_all",
                                "score",
                                "grade",
                                "provisional",
                                "prev",
                                "trend"
                            ],
                            "properties": {
                                "company": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "nickname": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "is_hq": {
                                    "type": "boolean"
                                },
                                "reviews": {
                                    "type": "integer"
                                },
                                "avg": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "reply_rate": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "total": {
                                    "type": "integer"
                                },
                                "avg_all": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "score": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "grade": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "provisional": {
                                    "type": "boolean",
                                    "nullable": true
                                },
                                "prev": {
                                    "$ref": "#/components/schemas/V1InsightsPrevCounts"
                                },
                                "trend": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                        "up",
                                        "down",
                                        "flat"
                                    ]
                                }
                            },
                            "type": "object"
                        },
                        "nullable": true
                    },
                    "tags": {
                        "description": "Review tags and sentiment (www/docs/review-tags.md): `sentiment`, `top` and `by_location` (null outside HQ views).",
                        "required": [
                            "sentiment",
                            "top",
                            "by_location"
                        ],
                        "properties": {
                            "sentiment": {
                                "type": "object",
                                "additionalProperties": true
                            },
                            "top": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "by_location": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                },
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "highlights": {
                        "description": "3-5 sentences written by fixed rules.",
                        "type": "array",
                        "items": {
                            "required": [
                                "key",
                                "text",
                                "tone"
                            ],
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "text": {
                                    "type": "string"
                                },
                                "tone": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1InsightsTheme": {
                "required": [
                    "label",
                    "attribute",
                    "summary",
                    "mentions",
                    "net",
                    "trend"
                ],
                "properties": {
                    "label": {
                        "type": "string"
                    },
                    "attribute": {
                        "type": "string",
                        "nullable": true
                    },
                    "summary": {
                        "type": "string"
                    },
                    "mentions": {
                        "type": "integer"
                    },
                    "net": {
                        "type": "number",
                        "nullable": true
                    },
                    "trend": {
                        "description": "Change of `net` since before the period.",
                        "type": "number",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewInsightsMeta": {
                "required": [
                    "from",
                    "to",
                    "previous_from",
                    "previous_to",
                    "timezone",
                    "compare",
                    "group",
                    "locations_count",
                    "source"
                ],
                "properties": {
                    "from": {
                        "type": "string",
                        "format": "date"
                    },
                    "to": {
                        "type": "string",
                        "format": "date"
                    },
                    "previous_from": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "previous_to": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "timezone": {
                        "type": "string"
                    },
                    "compare": {
                        "type": "string",
                        "enum": [
                            "prev",
                            "none"
                        ]
                    },
                    "group": {
                        "description": "The HQ and its locations are covered.",
                        "type": "boolean"
                    },
                    "locations_count": {
                        "type": "integer"
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "stored"
                        ]
                    }
                },
                "type": "object"
            },
            "V1Integration": {
                "properties": {
                    "platform": {
                        "type": "string",
                        "example": "square"
                    },
                    "name": {
                        "type": "string",
                        "example": "Square"
                    },
                    "auth": {
                        "type": "string",
                        "enum": [
                            "oauth",
                            "api_key"
                        ]
                    },
                    "delivery": {
                        "type": "string",
                        "enum": [
                            "webhook",
                            "poll"
                        ]
                    },
                    "beta": {
                        "type": "boolean"
                    },
                    "available": {
                        "description": "False: the platform is not open to this business yet (no credentials, or its launch status is off or an allowlist without this business).",
                        "type": "boolean"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "not_available",
                            "not_connected",
                            "connected",
                            "error"
                        ]
                    },
                    "trigger_kinds": {
                        "type": "array",
                        "items": {
                            "required": [
                                "key",
                                "label"
                            ],
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "sms_consent_field": {
                        "type": "string",
                        "nullable": true
                    },
                    "supports_value": {
                        "type": "boolean"
                    },
                    "requirements": {
                        "type": "string"
                    },
                    "key_fields": {
                        "description": "API-key platforms only: the fields to send.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1IntegrationKeyField"
                        },
                        "nullable": true
                    },
                    "regions": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "nullable": true
                    },
                    "connection": {
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1IntegrationKeyField": {
                "required": [
                    "name",
                    "label",
                    "required",
                    "secret"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "api_key"
                    },
                    "label": {
                        "type": "string"
                    },
                    "required": {
                        "type": "boolean"
                    },
                    "secret": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1IntegrationConnectLink": {
                "description": "OAuth platforms: `url` (single use, 15 minutes) and `expires_at`. API-key platforms: `url` null and the `key_fields` to send to `POST .../integrations/{platform}`.",
                "required": [
                    "auth",
                    "url",
                    "requirements"
                ],
                "properties": {
                    "auth": {
                        "type": "string",
                        "enum": [
                            "oauth",
                            "api_key"
                        ]
                    },
                    "url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "expires_at": {
                        "description": "OAuth only.",
                        "type": "string",
                        "format": "date-time"
                    },
                    "key_fields": {
                        "description": "API-key platforms only.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1IntegrationKeyField"
                        },
                        "nullable": true
                    },
                    "requirements": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1IntegrationTest": {
                "description": "The connection check and a made-up completed job run through the mapping and campaign checks (nothing created or sent).",
                "required": [
                    "connection",
                    "sample",
                    "contact",
                    "result",
                    "sent"
                ],
                "properties": {
                    "connection": {
                        "required": [
                            "ok",
                            "account",
                            "error"
                        ],
                        "properties": {
                            "ok": {
                                "type": "boolean"
                            },
                            "account": {
                                "properties": {
                                    "id": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "name": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            },
                            "error": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "sample": {
                        "required": [
                            "kind",
                            "label",
                            "customer"
                        ],
                        "properties": {
                            "kind": {
                                "type": "string"
                            },
                            "label": {
                                "type": "string",
                                "nullable": true
                            },
                            "customer": {
                                "properties": {
                                    "external_id": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "name": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "email": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "phone": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "sms_allowed": {
                                        "type": "boolean"
                                    },
                                    "email_opted_out": {
                                        "type": "boolean"
                                    },
                                    "do_not_contact": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "contact": {
                        "description": "The review request contact the job maps to.",
                        "required": [
                            "name",
                            "email",
                            "phone",
                            "email_consent_source",
                            "sms_consent"
                        ],
                        "properties": {
                            "name": {
                                "type": "string",
                                "nullable": true
                            },
                            "email": {
                                "type": "string",
                                "nullable": true
                            },
                            "phone": {
                                "type": "string",
                                "nullable": true
                            },
                            "email_consent_source": {
                                "type": "string",
                                "nullable": true
                            },
                            "sms_consent": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "result": {
                        "required": [
                            "would_create",
                            "reason"
                        ],
                        "properties": {
                            "would_create": {
                                "type": "boolean"
                            },
                            "reason": {
                                "description": "Why it would be skipped.",
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "sent": {
                        "description": "Always false.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1IntegrationSettingsInput": {
                "description": "Settings of a job-done integration (`IntegrationSettings::rules()`); every field optional, omitted = unchanged.",
                "properties": {
                    "campaign": {
                        "description": "Campaign uuid or `default`.",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 64
                    },
                    "delay_minutes": {
                        "description": "null = the campaign's first step.",
                        "type": "integer",
                        "nullable": true,
                        "maximum": 43200,
                        "minimum": 0
                    },
                    "trigger_kinds": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "maxLength": 40
                        },
                        "maxItems": 10,
                        "minItems": 1
                    },
                    "min_value": {
                        "description": "Platforms with amounts.",
                        "type": "number",
                        "nullable": true,
                        "maximum": 100000000,
                        "minimum": 0
                    },
                    "sms_enabled": {
                        "type": "boolean"
                    },
                    "sms_consent_text": {
                        "description": "The opt-in wording your customers agree to on the platform; must name Grades.com and STOP.",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 1000,
                        "minLength": 20
                    },
                    "paused": {
                        "type": "boolean"
                    },
                    "hubspot": {
                        "description": "HubSpot only.",
                        "properties": {
                            "deal_stages": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "maxLength": 100
                                }
                            },
                            "ticket_stages": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "maxLength": 100
                                }
                            },
                            "contact_sync": {
                                "type": "boolean"
                            },
                            "contact_sync_scope": {
                                "type": "string",
                                "enum": [
                                    "customers",
                                    "all"
                                ]
                            },
                            "writeback": {
                                "type": "boolean"
                            },
                            "writeback_text": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "shopify": {
                        "description": "Shopify only.",
                        "properties": {
                            "consent_mode": {
                                "type": "string",
                                "enum": [
                                    "confirmed_customers",
                                    "subscribed_only"
                                ]
                            },
                            "contact_confirmed": {
                                "type": "boolean"
                            },
                            "single_request": {
                                "type": "boolean"
                            },
                            "contact_sync": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1IntegrationConnectInput": {
                "description": "API keys of the platform (the names in `key_fields`; only some = keep the others) plus optional settings.",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1IntegrationSettingsInput"
                    },
                    {
                        "properties": {
                            "api_key": {
                                "description": "Housecall Pro.",
                                "type": "string",
                                "nullable": true,
                                "maxLength": 500,
                                "minLength": 4
                            },
                            "webhook_signing_secret": {
                                "description": "Housecall Pro.",
                                "type": "string",
                                "nullable": true,
                                "maxLength": 500,
                                "minLength": 4
                            },
                            "customer_key": {
                                "description": "Open Dental.",
                                "type": "string",
                                "nullable": true,
                                "maxLength": 500,
                                "minLength": 4
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1IntegrationSetup": {
                "description": "The setup guide an AI agent walks through (docs/connect-flows.md \"Agentic setup via MCP\").",
                "required": [
                    "status",
                    "status_note",
                    "install_url",
                    "dashboard_url",
                    "help_url",
                    "steps",
                    "human_only"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": [
                            "available",
                            "invite",
                            "in_review",
                            "coming_soon"
                        ]
                    },
                    "status_note": {
                        "type": "string"
                    },
                    "install_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "dashboard_url": {
                        "type": "string",
                        "format": "url"
                    },
                    "help_url": {
                        "type": "string",
                        "format": "url"
                    },
                    "steps": {
                        "type": "array",
                        "items": {
                            "required": [
                                "actor",
                                "text"
                            ],
                            "properties": {
                                "actor": {
                                    "type": "string",
                                    "enum": [
                                        "agent",
                                        "user",
                                        "agent_or_user"
                                    ]
                                },
                                "text": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "human_only": {
                        "description": "What only the person may do.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "type": "object"
            },
            "V1IntegrationPreset": {
                "required": [
                    "integration",
                    "name",
                    "key_type",
                    "scopes",
                    "businesses",
                    "summary",
                    "steps",
                    "setup"
                ],
                "properties": {
                    "integration": {
                        "type": "string",
                        "example": "make"
                    },
                    "name": {
                        "type": "string",
                        "example": "Make"
                    },
                    "key_type": {
                        "type": "string",
                        "enum": [
                            "secret",
                            "publishable"
                        ]
                    },
                    "scopes": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "businesses": {
                        "description": "`any`: all or some businesses; `one`: exactly one.",
                        "type": "string",
                        "enum": [
                            "any",
                            "one"
                        ]
                    },
                    "summary": {
                        "type": "string"
                    },
                    "steps": {
                        "description": "Paste steps; `**text**` marks the tool's own labels.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "setup": {
                        "$ref": "#/components/schemas/V1IntegrationSetup"
                    }
                },
                "type": "object"
            },
            "V1IntegrationKey": {
                "description": "An integration key (never the secret, except `key` right after it was created).",
                "required": [
                    "type",
                    "id",
                    "integration",
                    "name",
                    "label",
                    "prefix",
                    "scopes",
                    "businesses",
                    "created_via",
                    "created_by_client",
                    "created_at",
                    "last_used_at",
                    "expires_at",
                    "revoked_at"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "secret",
                            "publishable"
                        ]
                    },
                    "id": {
                        "type": "integer"
                    },
                    "integration": {
                        "type": "string",
                        "nullable": true
                    },
                    "name": {
                        "type": "string",
                        "nullable": true
                    },
                    "label": {
                        "type": "string"
                    },
                    "url_key": {
                        "description": "Secret keys only: a reporting URL key.",
                        "type": "boolean"
                    },
                    "prefix": {
                        "type": "string",
                        "nullable": true
                    },
                    "scopes": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "businesses": {
                        "required": [
                            "all",
                            "companies"
                        ],
                        "properties": {
                            "all": {
                                "type": "boolean"
                            },
                            "companies": {
                                "type": "array",
                                "items": {
                                    "required": [
                                        "uuid",
                                        "name"
                                    ],
                                    "properties": {
                                        "uuid": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "name": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "created_via": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_by_client": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_used_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "revoked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1IntegrationKeyGroup": {
                "required": [
                    "integration",
                    "name",
                    "key_type",
                    "keys",
                    "webhooks"
                ],
                "properties": {
                    "integration": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "key_type": {
                        "type": "string",
                        "enum": [
                            "secret",
                            "publishable"
                        ]
                    },
                    "keys": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1IntegrationKey"
                        }
                    },
                    "webhooks": {
                        "description": "Webhooks the integration subscribed, with the last delivery.",
                        "type": "array",
                        "items": {
                            "required": [
                                "id",
                                "host",
                                "description",
                                "events",
                                "company",
                                "active",
                                "made_with_key",
                                "last_delivered_at",
                                "last_delivery",
                                "disabled_at"
                            ],
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "host": {
                                    "type": "string"
                                },
                                "description": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "events": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "company": {
                                    "description": "Company uuid.",
                                    "type": "string",
                                    "nullable": true
                                },
                                "active": {
                                    "type": "boolean"
                                },
                                "made_with_key": {
                                    "description": "Key id.",
                                    "type": "integer",
                                    "nullable": true
                                },
                                "last_delivered_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "last_delivery": {
                                    "required": [
                                        "status",
                                        "response_code",
                                        "at"
                                    ],
                                    "properties": {
                                        "status": {
                                            "type": "string"
                                        },
                                        "response_code": {
                                            "type": "integer",
                                            "nullable": true
                                        },
                                        "at": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object",
                                    "nullable": true
                                },
                                "disabled_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1LocationRef": {
                "description": "A company of an HQ group (the HQ or one of its locations).",
                "required": [
                    "uuid",
                    "name",
                    "location_nickname",
                    "slug",
                    "is_hq",
                    "city",
                    "state"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "location_nickname": {
                        "type": "string",
                        "nullable": true
                    },
                    "slug": {
                        "type": "string"
                    },
                    "is_hq": {
                        "type": "boolean"
                    },
                    "city": {
                        "type": "string",
                        "nullable": true
                    },
                    "state": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1LocationListItem": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1LocationRef"
                    },
                    {
                        "required": [
                            "timezone",
                            "role"
                        ],
                        "properties": {
                            "timezone": {
                                "type": "string",
                                "nullable": true
                            },
                            "role": {
                                "description": "The caller's role in this company (null for none).",
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1LocationMetrics": {
                "description": "Review metrics of a period (`new_*`, `responded`, `response_rate`, `unanswered_negative`) against the previous period (`previous_*`), plus all-time totals.",
                "required": [
                    "reviews_total",
                    "rating_average",
                    "new_reviews",
                    "new_rating_average",
                    "previous_new_reviews",
                    "previous_rating_average",
                    "responded",
                    "response_rate",
                    "unanswered_negative",
                    "rating_distribution",
                    "pending_agent_actions",
                    "low_ratings",
                    "unanswered"
                ],
                "properties": {
                    "reviews_total": {
                        "type": "integer"
                    },
                    "rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "new_reviews": {
                        "type": "integer"
                    },
                    "new_rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "previous_new_reviews": {
                        "type": "integer"
                    },
                    "previous_rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "responded": {
                        "type": "integer"
                    },
                    "response_rate": {
                        "type": "number",
                        "nullable": true
                    },
                    "unanswered_negative": {
                        "type": "integer"
                    },
                    "rating_distribution": {
                        "description": "New reviews of the period per star rating, keys \"5\" .. \"1\".",
                        "type": "object",
                        "additionalProperties": {
                            "type": "integer"
                        }
                    },
                    "pending_agent_actions": {
                        "type": "integer"
                    },
                    "low_ratings": {
                        "type": "integer"
                    },
                    "unanswered": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1LocationConnections": {
                "description": "Connection health of a location's review sites (docs/multi-location.md \"Connections\").",
                "required": [
                    "status",
                    "google",
                    "issues"
                ],
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": [
                            "ok",
                            "attention"
                        ]
                    },
                    "google": {
                        "type": "string",
                        "enum": [
                            "connected",
                            "reconnect",
                            "not_connected"
                        ]
                    },
                    "issues": {
                        "type": "array",
                        "items": {
                            "required": [
                                "platform",
                                "name",
                                "state"
                            ],
                            "properties": {
                                "platform": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "state": {
                                    "type": "string",
                                    "enum": [
                                        "reconnect",
                                        "failing",
                                        "not_connected"
                                    ]
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1LocationStats": {
                "required": [
                    "totals",
                    "locations",
                    "sources",
                    "platforms"
                ],
                "properties": {
                    "totals": {
                        "$ref": "#/components/schemas/V1LocationMetrics"
                    },
                    "locations": {
                        "type": "array",
                        "items": {
                            "allOf": [
                                {
                                    "$ref": "#/components/schemas/V1LocationMetrics"
                                },
                                {
                                    "required": [
                                        "location",
                                        "connections",
                                        "rank"
                                    ],
                                    "properties": {
                                        "location": {
                                            "$ref": "#/components/schemas/V1LocationRef"
                                        },
                                        "connections": {
                                            "$ref": "#/components/schemas/V1LocationConnections"
                                        },
                                        "rank": {
                                            "description": "1 = first for metric sorts; null when sorted by name.",
                                            "type": "integer",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            ]
                        }
                    },
                    "sources": {
                        "description": "One row per review source driver (internal ids).",
                        "type": "array",
                        "items": {
                            "required": [
                                "source",
                                "site",
                                "name",
                                "reviews_total",
                                "rating_average",
                                "new_reviews",
                                "new_rating_average",
                                "response_rate"
                            ],
                            "properties": {
                                "source": {
                                    "type": "string"
                                },
                                "site": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "reviews_total": {
                                    "type": "integer"
                                },
                                "rating_average": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "new_reviews": {
                                    "type": "integer"
                                },
                                "new_rating_average": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "response_rate": {
                                    "type": "number",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "platforms": {
                        "description": "One row per review platform (the drivers of one platform merged).",
                        "type": "array",
                        "items": {
                            "required": [
                                "platform",
                                "name",
                                "sources",
                                "reviews_total",
                                "rating_average",
                                "new_reviews",
                                "new_rating_average",
                                "response_rate",
                                "previous_new_reviews",
                                "previous_rating_average"
                            ],
                            "properties": {
                                "platform": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "sources": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "reviews_total": {
                                    "type": "integer"
                                },
                                "rating_average": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "new_reviews": {
                                    "type": "integer"
                                },
                                "new_rating_average": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "response_rate": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "previous_new_reviews": {
                                    "type": "integer"
                                },
                                "previous_rating_average": {
                                    "type": "number",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1LocationReviewPage": {
                "description": "The copyable settings of a location's default review page.",
                "required": [
                    "id",
                    "slug",
                    "url",
                    "enabled",
                    "headline",
                    "intro",
                    "closing",
                    "accent_color",
                    "theme",
                    "show_logo",
                    "show_feedback_form",
                    "feedback_email"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "enabled": {
                        "type": "boolean"
                    },
                    "headline": {
                        "type": "string",
                        "nullable": true
                    },
                    "intro": {
                        "type": "string",
                        "nullable": true
                    },
                    "closing": {
                        "type": "string",
                        "nullable": true
                    },
                    "accent_color": {
                        "type": "string",
                        "nullable": true
                    },
                    "theme": {
                        "type": "string",
                        "nullable": true
                    },
                    "show_logo": {
                        "type": "boolean",
                        "nullable": true
                    },
                    "show_feedback_form": {
                        "type": "boolean"
                    },
                    "feedback_email": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1LocationSettingsRow": {
                "required": [
                    "location",
                    "agent",
                    "review_page"
                ],
                "properties": {
                    "location": {
                        "$ref": "#/components/schemas/V1LocationRef"
                    },
                    "agent": {
                        "description": "The location's review agent settings: the fields of `V1AgentSettings` without `last_triaged_at` and `updated_at`.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "review_page": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/V1LocationReviewPage"
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "V1LocationSettingsResult": {
                "required": [
                    "location",
                    "status",
                    "error",
                    "agent",
                    "review_page"
                ],
                "properties": {
                    "location": {
                        "$ref": "#/components/schemas/V1LocationRef"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "applied",
                            "failed"
                        ]
                    },
                    "error": {
                        "description": "Why a location failed (null when applied).",
                        "required": [
                            "code",
                            "detail",
                            "http_status"
                        ],
                        "properties": {
                            "code": {
                                "type": "string"
                            },
                            "detail": {
                                "type": "string"
                            },
                            "http_status": {
                                "type": "integer"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "agent": {
                        "description": "The saved agent settings (fields of `V1AgentSettings` without `last_triaged_at` and `updated_at`); null when `agent` was not sent or the location failed.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "review_page": {
                        "description": "The saved default review page; null when `review_page` was not sent or the location failed.",
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/V1LocationReviewPage"
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "V1LocationMember": {
                "required": [
                    "uuid",
                    "name",
                    "email",
                    "role",
                    "status",
                    "all_locations",
                    "locations"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string"
                    },
                    "role": {
                        "description": "Role in the HQ.",
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "accepted",
                            "pending"
                        ]
                    },
                    "all_locations": {
                        "description": "The HQ membership covers every location.",
                        "type": "boolean"
                    },
                    "locations": {
                        "description": "Locations the user is also a direct member of.",
                        "type": "array",
                        "items": {
                            "required": [
                                "uuid",
                                "name",
                                "role"
                            ],
                            "properties": {
                                "uuid": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "role": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1LocationHq": {
                "required": [
                    "uuid",
                    "name"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1PlatformBrowserAccount": {
                "description": "A Grades-owned reporter account (`scope` platform) with its usage.",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1BrowserSession"
                    },
                    {
                        "required": [
                            "usage"
                        ],
                        "properties": {
                            "usage": {
                                "required": [
                                    "site_actions_24h",
                                    "daily_limit"
                                ],
                                "properties": {
                                    "site_actions_24h": {
                                        "type": "integer"
                                    },
                                    "daily_limit": {
                                        "type": "integer"
                                    }
                                },
                                "type": "object"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1PlatformReporterAccountPlan": {
                "description": "The planned reporter account of a site (configuration): sign-up address, page, password-manager entry.",
                "required": [
                    "email",
                    "signup_url",
                    "passbolt",
                    "note"
                ],
                "properties": {
                    "email": {
                        "type": "string",
                        "nullable": true
                    },
                    "signup_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "passbolt": {
                        "type": "string",
                        "nullable": true
                    },
                    "note": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1PlatformBrowserAccountListMeta": {
                "required": [
                    "enabled",
                    "worker_available",
                    "connect",
                    "sites",
                    "consent_version",
                    "daily_limit",
                    "planned_sites",
                    "report_jobs"
                ],
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "worker_available": {
                        "type": "boolean"
                    },
                    "connect": {
                        "$ref": "#/components/schemas/V1BrowserConnectMeta"
                    },
                    "sites": {
                        "description": "The platform report sites.",
                        "type": "array",
                        "items": {
                            "allOf": [
                                {
                                    "$ref": "#/components/schemas/V1BrowserConnectSite"
                                },
                                {
                                    "required": [
                                        "account"
                                    ],
                                    "properties": {
                                        "account": {
                                            "$ref": "#/components/schemas/V1PlatformReporterAccountPlan"
                                        }
                                    },
                                    "type": "object"
                                }
                            ]
                        }
                    },
                    "consent_version": {
                        "type": "string"
                    },
                    "daily_limit": {
                        "type": "integer"
                    },
                    "planned_sites": {
                        "description": "Sites whose handling plans a reporter account that cannot report yet.",
                        "type": "array",
                        "items": {
                            "required": [
                                "site",
                                "label",
                                "status",
                                "account_type",
                                "account"
                            ],
                            "properties": {
                                "site": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "account_type": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "account": {
                                    "$ref": "#/components/schemas/V1PlatformReporterAccountPlan"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "report_jobs": {
                        "description": "The latest 25 browser report jobs of every account, newest first.",
                        "type": "array",
                        "items": {
                            "required": [
                                "uuid",
                                "site",
                                "account",
                                "status",
                                "status_text",
                                "rehearsal",
                                "stopped_before",
                                "error_code",
                                "attempts",
                                "company",
                                "action",
                                "created_at",
                                "completed_at",
                                "evidence_url"
                            ],
                            "properties": {
                                "uuid": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "site": {
                                    "type": "string"
                                },
                                "account": {
                                    "description": "The scope of the account used.",
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                        "company",
                                        "platform"
                                    ]
                                },
                                "status": {
                                    "type": "string",
                                    "enum": [
                                        "queued",
                                        "claimed",
                                        "succeeded",
                                        "failed",
                                        "needs_owner",
                                        "canceled",
                                        "rehearsed"
                                    ]
                                },
                                "status_text": {
                                    "type": "string"
                                },
                                "rehearsal": {
                                    "type": "boolean"
                                },
                                "stopped_before": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "error_code": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "attempts": {
                                    "type": "integer"
                                },
                                "company": {
                                    "required": [
                                        "uuid",
                                        "name"
                                    ],
                                    "properties": {
                                        "uuid": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "name": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object",
                                    "nullable": true
                                },
                                "action": {
                                    "description": "The agent action uuid.",
                                    "type": "string",
                                    "nullable": true
                                },
                                "created_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "completed_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "evidence_url": {
                                    "type": "string",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1RadarScan": {
                "required": [
                    "id",
                    "kind",
                    "trigger",
                    "status",
                    "cost_usd",
                    "stats",
                    "error",
                    "started_at",
                    "finished_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "search",
                            "ai_probe"
                        ]
                    },
                    "trigger": {
                        "type": "string",
                        "enum": [
                            "manual",
                            "schedule"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "running",
                            "succeeded",
                            "partial",
                            "failed"
                        ]
                    },
                    "cost_usd": {
                        "type": "number",
                        "format": "float"
                    },
                    "stats": {
                        "description": "Counters of the run (free-form). AI probe runs: `errors` maps \"engine|prompt\" to a code (engine_busy, engine_timeout, engine_unavailable, engine_declined, engine_error), never the provider's message.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "error": {
                        "type": "string",
                        "nullable": true
                    },
                    "started_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "finished_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AiReputationMeasures": {
                "description": "The four AI Reputation measures of the latest answer of each assistant (docs/review-radar.md \"AI Reputation measures\"). `mentioned` and `rating_accuracy` are null until there is something to measure.",
                "properties": {
                    "engines": {
                        "description": "Assistants with an answer.",
                        "type": "integer"
                    },
                    "mentioned": {
                        "description": "\"Mentioned by `count` of `of` assistants\": `of` = assistants whose answers were judged.",
                        "properties": {
                            "count": {
                                "type": "integer"
                            },
                            "of": {
                                "type": "integer"
                            },
                            "wrong_entity": {
                                "description": "Assistants that described a different business.",
                                "type": "integer"
                            },
                            "by_engine": {
                                "description": "engine => yes | no | wrong_entity | null",
                                "type": "object"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "sentiment": {
                        "description": "Assistants per overall sentiment.",
                        "type": "object"
                    },
                    "rating_accuracy": {
                        "description": "\"`accurate` of `checked` quotes correct\" (a quote repeated by one assistant counts once); `unknown_site` quotes could not be compared; `share` = accurate / checked.",
                        "properties": {
                            "accurate": {
                                "type": "integer"
                            },
                            "stale": {
                                "type": "integer"
                            },
                            "wrong": {
                                "type": "integer"
                            },
                            "unknown_site": {
                                "type": "integer"
                            },
                            "checked": {
                                "type": "integer"
                            },
                            "share": {
                                "type": "number",
                                "format": "float",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "review_sites_cited": {
                        "properties": {
                            "count": {
                                "type": "integer"
                            },
                            "domains": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "facts": {
                        "description": "What the assistants state about the business that is not a complaint (docs/review-radar.md \"Business facts and suggested actions\"), one row per topic across the assistants' latest answers: the first sentence, the assistants that said it, first / last seen in the answers read and the suggested action (null for `other` or an unmapped topic). Never an alert.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "topic": {
                                    "type": "string",
                                    "example": "no_prices_listed"
                                },
                                "label": {
                                    "type": "string",
                                    "example": "No prices on its website"
                                },
                                "text": {
                                    "type": "string"
                                },
                                "engines": {
                                    "type": "array",
                                    "items": {
                                        "type": "string",
                                        "enum": [
                                            "gemini",
                                            "openai",
                                            "perplexity",
                                            "anthropic"
                                        ]
                                    }
                                },
                                "engine_labels": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "first_seen_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "last_seen_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "action": {
                                    "properties": {
                                        "label": {
                                            "type": "string",
                                            "example": "Publish pricing or a starting-from range on your website"
                                        },
                                        "text": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "link": {
                                            "type": "string",
                                            "enum": [
                                                "external",
                                                "dashboard",
                                                "none"
                                            ]
                                        },
                                        "url": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "plan": {
                                            "description": "The plan the linked feature needs (a note).",
                                            "type": "string",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1RadarSettings": {
                "required": [
                    "enabled",
                    "default",
                    "search_available",
                    "ai_engines",
                    "last_scan",
                    "last_ai_probe",
                    "updated_at"
                ],
                "properties": {
                    "enabled": {
                        "description": "The weekly scan and AI probe run.",
                        "type": "boolean"
                    },
                    "default": {
                        "description": "No saved toggle: `enabled` is the plan's default.",
                        "type": "boolean"
                    },
                    "search_available": {
                        "description": "The server has an Apify token.",
                        "type": "boolean"
                    },
                    "ai_engines": {
                        "description": "AI engines with an API key on the server.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "gemini",
                                "openai",
                                "perplexity",
                                "anthropic"
                            ]
                        }
                    },
                    "last_scan": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/V1RadarScan"
                            }
                        ]
                    },
                    "last_ai_probe": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/V1RadarScan"
                            }
                        ]
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1RadarScanResult": {
                "required": [
                    "scan",
                    "new_mentions"
                ],
                "properties": {
                    "scan": {
                        "$ref": "#/components/schemas/V1RadarScan"
                    },
                    "new_mentions": {
                        "description": "Mentions first seen by this scan (at most 200).",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewMention"
                        }
                    }
                },
                "type": "object"
            },
            "V1AiRatingAccuracyTally": {
                "required": [
                    "accurate",
                    "stale",
                    "wrong",
                    "unknown_site",
                    "checked"
                ],
                "properties": {
                    "accurate": {
                        "type": "integer"
                    },
                    "stale": {
                        "type": "integer"
                    },
                    "wrong": {
                        "type": "integer"
                    },
                    "unknown_site": {
                        "type": "integer"
                    },
                    "checked": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1AiProbeEngineSummary": {
                "description": "One engine's answers of one run summed up.",
                "required": [
                    "engine",
                    "engine_label",
                    "sentiment",
                    "score",
                    "summary",
                    "rating_claims",
                    "negative_claims",
                    "mentioned_sites",
                    "cited_domains",
                    "run_at",
                    "mentioned",
                    "mentioned_reason",
                    "rating_quotes",
                    "rating_accuracy",
                    "business_facts"
                ],
                "properties": {
                    "engine": {
                        "type": "string",
                        "enum": [
                            "gemini",
                            "openai",
                            "perplexity",
                            "anthropic"
                        ]
                    },
                    "engine_label": {
                        "type": "string"
                    },
                    "sentiment": {
                        "description": "Overall sentiment of the answers.",
                        "type": "string",
                        "enum": [
                            "positive",
                            "mixed",
                            "negative",
                            "unknown"
                        ]
                    },
                    "score": {
                        "type": "number",
                        "format": "float",
                        "nullable": true
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true
                    },
                    "rating_claims": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "negative_claims": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "mentioned_sites": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "cited_domains": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "run_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "mentioned": {
                        "description": "`yes`, `no` or `wrong_entity`; null when no answer was judged.",
                        "type": "string",
                        "nullable": true
                    },
                    "mentioned_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "rating_quotes": {
                        "description": "The checked rating quotes of the answers (each quote once), as in `V1AiProbe.rating_quotes`.",
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "rating_accuracy": {
                        "$ref": "#/components/schemas/V1AiRatingAccuracyTally"
                    },
                    "business_facts": {
                        "type": "array",
                        "items": {
                            "required": [
                                "topic",
                                "label",
                                "text",
                                "engine"
                            ],
                            "properties": {
                                "topic": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "text": {
                                    "type": "string"
                                },
                                "engine": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1AiProbeRunResult": {
                "required": [
                    "run",
                    "summary",
                    "measures",
                    "changes",
                    "probes"
                ],
                "properties": {
                    "run": {
                        "$ref": "#/components/schemas/V1RadarScan"
                    },
                    "summary": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AiProbeEngineSummary"
                        }
                    },
                    "measures": {
                        "$ref": "#/components/schemas/V1AiReputationMeasures"
                    },
                    "changes": {
                        "description": "Per engine: new complaints against the previous run.",
                        "type": "array",
                        "items": {
                            "required": [
                                "engine",
                                "from",
                                "to",
                                "new_negative_claims"
                            ],
                            "properties": {
                                "engine": {
                                    "type": "string"
                                },
                                "from": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "to": {
                                    "type": "string"
                                },
                                "new_negative_claims": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            },
                            "type": "object"
                        }
                    },
                    "probes": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AiProbe"
                        }
                    }
                },
                "type": "object"
            },
            "V1AiProbeRunMeta": {
                "required": [
                    "engines_used",
                    "engines_skipped",
                    "cost_usd",
                    "max_cost_usd"
                ],
                "properties": {
                    "engines_used": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "engines_skipped": {
                        "description": "engine => reason (e.g. `no_api_key`).",
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    },
                    "cost_usd": {
                        "type": "number",
                        "format": "float"
                    },
                    "max_cost_usd": {
                        "type": "number",
                        "format": "float"
                    }
                },
                "type": "object"
            },
            "V1AiPerception": {
                "required": [
                    "summary",
                    "measures",
                    "probes",
                    "history"
                ],
                "properties": {
                    "summary": {
                        "description": "The latest judged run per engine.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AiProbeEngineSummary"
                        }
                    },
                    "measures": {
                        "$ref": "#/components/schemas/V1AiReputationMeasures"
                    },
                    "probes": {
                        "description": "The answers of those latest runs.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1AiProbe"
                        }
                    },
                    "history": {
                        "description": "One row per run and engine, newest first (at most 100).",
                        "type": "array",
                        "items": {
                            "required": [
                                "run_id",
                                "engine",
                                "run_at",
                                "sentiment",
                                "score",
                                "rating_claims",
                                "mentioned",
                                "rating_accuracy",
                                "business_facts"
                            ],
                            "properties": {
                                "run_id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "engine": {
                                    "type": "string",
                                    "enum": [
                                        "gemini",
                                        "openai",
                                        "perplexity",
                                        "anthropic"
                                    ]
                                },
                                "run_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "sentiment": {
                                    "type": "string",
                                    "enum": [
                                        "positive",
                                        "mixed",
                                        "negative",
                                        "unknown"
                                    ]
                                },
                                "score": {
                                    "type": "number",
                                    "format": "float",
                                    "nullable": true
                                },
                                "rating_claims": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "mentioned": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "rating_accuracy": {
                                    "$ref": "#/components/schemas/V1AiRatingAccuracyTally"
                                },
                                "business_facts": {
                                    "description": "Topics of the facts the answers stated.",
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1AiPerceptionMeta": {
                "required": [
                    "engines_configured",
                    "engines_skipped",
                    "last_run",
                    "cadence"
                ],
                "properties": {
                    "engines_configured": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "engines_skipped": {
                        "description": "engine => `no_api_key` for engines without a key on the server.",
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    },
                    "last_run": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/V1RadarScan"
                            }
                        ]
                    },
                    "cadence": {
                        "required": [
                            "days",
                            "label",
                            "scheduled",
                            "next_check_at"
                        ],
                        "properties": {
                            "days": {
                                "type": "integer",
                                "nullable": true
                            },
                            "label": {
                                "type": "string",
                                "nullable": true
                            },
                            "scheduled": {
                                "type": "boolean"
                            },
                            "next_check_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1RecoveryCaseEvent": {
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "type": {
                        "type": "string"
                    },
                    "user": {
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "channel": {
                        "type": "string",
                        "nullable": true
                    },
                    "to_address": {
                        "type": "string",
                        "nullable": true
                    },
                    "data": {
                        "description": "Event details; free-form per `type`.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1RecoveryCase": {
                "description": "A recovery case. Yelp text (`review.text`, `review.author`, and a customer name that is only that author) is null with `review.text_policy` set unless the caller may read it.",
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "company": {
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            },
                            "location_nickname": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "review",
                            "feedback",
                            "escalation"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "new",
                            "contacted",
                            "resolved",
                            "closed"
                        ]
                    },
                    "outcome": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "resolved",
                            "no_response",
                            "declined",
                            "not_applicable"
                        ]
                    },
                    "rating": {
                        "type": "integer",
                        "nullable": true
                    },
                    "opened_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "first_contact_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "resolved_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "closed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "update_asked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "review_updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "review_rating_after": {
                        "type": "integer",
                        "nullable": true
                    },
                    "hours_without_contact": {
                        "description": "Open cases never contacted: hours since opening (1 decimal); else null.",
                        "type": "number",
                        "nullable": true
                    },
                    "assignee": {
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "customer": {
                        "properties": {
                            "name": {
                                "type": "string",
                                "nullable": true
                            },
                            "email": {
                                "type": "string",
                                "nullable": true
                            },
                            "phone": {
                                "type": "string",
                                "nullable": true
                            },
                            "contact": {
                                "description": "The linked review-request contact.",
                                "properties": {
                                    "uuid": {
                                        "type": "string",
                                        "format": "uuid"
                                    },
                                    "name": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "email": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "phone": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "sms_consent": {
                                        "type": "boolean"
                                    },
                                    "email_ok": {
                                        "type": "boolean"
                                    },
                                    "email_issue": {
                                        "description": "Why e-mail cannot be sent.",
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "sms_ok": {
                                        "type": "boolean"
                                    },
                                    "sms_issue": {
                                        "description": "Why SMS cannot be sent.",
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "review": {
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "site": {
                                "type": "string"
                            },
                            "site_name": {
                                "type": "string"
                            },
                            "source_kind": {
                                "type": "string"
                            },
                            "source_phrase": {
                                "type": "string"
                            },
                            "origin_name": {
                                "type": "string",
                                "nullable": true
                            },
                            "arrival": {
                                "type": "string"
                            },
                            "driver": {
                                "type": "string"
                            },
                            "author": {
                                "type": "string",
                                "nullable": true
                            },
                            "rating": {
                                "type": "integer",
                                "nullable": true
                            },
                            "text": {
                                "type": "string",
                                "nullable": true
                            },
                            "text_policy": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "aggregate"
                                ]
                            },
                            "text_hint": {
                                "type": "string",
                                "nullable": true
                            },
                            "published_date": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "url": {
                                "type": "string",
                                "nullable": true
                            },
                            "replied": {
                                "type": "boolean"
                            },
                            "removed": {
                                "type": "boolean"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "feedback": {
                        "description": "Review page feedback the case was opened from.",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "rating": {
                                "type": "integer",
                                "nullable": true
                            },
                            "name": {
                                "type": "string",
                                "nullable": true
                            },
                            "email": {
                                "type": "string",
                                "nullable": true
                            },
                            "message": {
                                "type": "string"
                            },
                            "created_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "agent_action": {
                        "description": "The review agent's reply draft for the review.",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "type": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string"
                            },
                            "escalated": {
                                "type": "boolean"
                            },
                            "pending": {
                                "type": "boolean"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "ask_update": {
                        "description": "Whether the update invitation can be sent now.",
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "reason": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "already_asked",
                                    "no_review",
                                    "review_removed",
                                    "site_forbids_requests",
                                    "no_review_link",
                                    "no_contact"
                                ]
                            },
                            "link": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "events": {
                        "description": "The case history, oldest first (single-case responses only, not in the list).",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1RecoveryCaseEvent"
                        }
                    }
                },
                "type": "object"
            },
            "V1RecoverySettings": {
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "open_max_rating": {
                        "description": "Reviews at or below this rating open a case.",
                        "type": "integer"
                    },
                    "feedback_open_max_rating": {
                        "type": "integer"
                    },
                    "sending_enabled": {
                        "type": "boolean"
                    },
                    "templates": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "subject": {
                                    "type": "string"
                                },
                                "body": {
                                    "type": "string"
                                },
                                "sms": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "merge_fields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "ask_update_text": {
                        "type": "string"
                    },
                    "ask_update_extra_max": {
                        "type": "integer"
                    },
                    "max_chars": {
                        "properties": {
                            "email": {
                                "type": "integer"
                            },
                            "sms": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewHandling": {
                "description": "The resolved rung of a site's ladder for this company: `channel` api | client_login | platform_account | anonymous_report | manual, `automated` (Grades.com carries it out), `connect_url` when connecting the business's own account would unlock more, `manual_url` / `next_steps` for the path that needs no login, and the whole `ladder`.",
                "properties": {
                    "kind": {
                        "type": "string",
                        "enum": [
                            "reply",
                            "report"
                        ]
                    },
                    "site": {
                        "type": "string"
                    },
                    "site_label": {
                        "type": "string"
                    },
                    "channel": {
                        "type": "string",
                        "enum": [
                            "api",
                            "client_login",
                            "platform_account",
                            "anonymous_report",
                            "manual"
                        ]
                    },
                    "channel_label": {
                        "type": "string"
                    },
                    "automated": {
                        "type": "boolean"
                    },
                    "how": {
                        "type": "string",
                        "nullable": true
                    },
                    "via": {
                        "type": "string",
                        "nullable": true
                    },
                    "report_url": {
                        "description": "The anonymous report link (channel `anonymous_report`), else null.",
                        "type": "string",
                        "nullable": true
                    },
                    "portal_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "connect_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "connect_label": {
                        "type": "string",
                        "nullable": true
                    },
                    "manual_url": {
                        "description": "Per review only.",
                        "type": "string",
                        "nullable": true
                    },
                    "next_steps": {
                        "description": "Per review only.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "ladder": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewHandlingRung"
                        }
                    }
                },
                "type": "object"
            },
            "V1ReviewHandlingRung": {
                "description": "One rung of a site's ladder (`config/review_policies.php`) and whether the company can use it now.",
                "required": [
                    "channel",
                    "status",
                    "label",
                    "available",
                    "automated",
                    "connectable",
                    "via",
                    "verified",
                    "form_fields",
                    "proxy",
                    "can",
                    "how",
                    "portal_url",
                    "two_factor",
                    "account_type",
                    "access",
                    "terms",
                    "terms_url",
                    "evidence",
                    "lag"
                ],
                "properties": {
                    "channel": {
                        "type": "string",
                        "enum": [
                            "api",
                            "client_login",
                            "platform_account",
                            "anonymous_report",
                            "manual"
                        ]
                    },
                    "status": {
                        "description": "E.g. `live`, `planned`, `not_allowed`.",
                        "type": "string"
                    },
                    "label": {
                        "type": "string"
                    },
                    "available": {
                        "type": "boolean"
                    },
                    "automated": {
                        "type": "boolean"
                    },
                    "connectable": {
                        "description": "Connecting the business's own account would make it available.",
                        "type": "boolean"
                    },
                    "via": {
                        "type": "string",
                        "nullable": true
                    },
                    "verified": {
                        "type": "boolean"
                    },
                    "form_fields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "proxy": {
                        "type": "string",
                        "nullable": true
                    },
                    "can": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "how": {
                        "type": "string",
                        "nullable": true
                    },
                    "portal_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "two_factor": {
                        "type": "string",
                        "nullable": true
                    },
                    "account_type": {
                        "type": "string",
                        "nullable": true
                    },
                    "access": {
                        "type": "string",
                        "nullable": true
                    },
                    "terms": {
                        "type": "string",
                        "nullable": true
                    },
                    "terms_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "evidence": {
                        "type": "string",
                        "nullable": true
                    },
                    "lag": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SourceHandling": {
                "description": "How replies to and reports of a connected source's reviews are handled.",
                "required": [
                    "driver",
                    "site",
                    "site_label",
                    "reply",
                    "report"
                ],
                "properties": {
                    "driver": {
                        "type": "string"
                    },
                    "site": {
                        "type": "string"
                    },
                    "site_label": {
                        "type": "string"
                    },
                    "reply": {
                        "$ref": "#/components/schemas/V1ReviewHandling"
                    },
                    "report": {
                        "$ref": "#/components/schemas/V1ReviewHandling"
                    }
                },
                "type": "object"
            },
            "V1ReviewPageLinkInput": {
                "description": "A source link (`source_id`, or `driver` = the company's source of that site; optional `label`, `url` override) or a custom link (`label` + `url`). `type` may be omitted.",
                "properties": {
                    "id": {
                        "description": "In a full `links` list: keeps that link's id.",
                        "type": "string"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "source",
                            "custom"
                        ]
                    },
                    "source_id": {
                        "type": "integer"
                    },
                    "driver": {
                        "type": "string",
                        "example": "yelp"
                    },
                    "label": {
                        "type": "string",
                        "maxLength": 80
                    },
                    "url": {
                        "description": "A URL on a link-only review site (`link_sites` of the page: Cars.com, Nextdoor, ...) must be a business page of that site and is stored clean (https, no query); 400 `body.url` otherwise.",
                        "type": "string",
                        "maxLength": 2048
                    },
                    "site": {
                        "description": "Custom links: the key of a link-only review site (`link_sites[].key`, e.g. `cars_com`); the URL must be on it, the label defaults to its name. Review link only: nothing is collected or monitored.",
                        "type": "string",
                        "example": "cars_com"
                    },
                    "enabled": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1ReviewPageSettings": {
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 80
                    },
                    "slug": {
                        "description": "3-40 lowercase letters, digits and dashes, unique in the company; reserved: default, qr, feedback, new, edit, api, admin, r, www, app, static, assets, review, reviews.",
                        "type": "string"
                    },
                    "enabled": {
                        "type": "boolean"
                    },
                    "headline": {
                        "description": "Plain text (shown escaped); null or \"\" = \"How did we do?\". Text that offers anything for a review or asks only happy customers / for positive reviews is refused (400, rule named).",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 120
                    },
                    "intro": {
                        "description": "Plain text, line breaks kept; null or \"\" = the default intro.",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 500
                    },
                    "closing": {
                        "description": "Closing line under the buttons; null or \"\" = none. Same text rules as headline and intro.",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 200
                    },
                    "display_name": {
                        "description": "Business name the page shows; null or \"\" = the company name.",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 120
                    },
                    "accent_color": {
                        "description": "Button outlines, the feedback button and focus rings; null = #4f46e5. A color that would be hard to read on the page is shown in a darker or lighter shade (`appearance.accent_adjusted`).",
                        "type": "string",
                        "pattern": "^#[0-9a-fA-F]{6}$",
                        "nullable": true
                    },
                    "theme": {
                        "description": "light or dark; null = light.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "light",
                            "dark"
                        ]
                    },
                    "show_logo": {
                        "description": "Show the company logo (uploaded in the dashboard) above the name; null = true.",
                        "type": "boolean",
                        "nullable": true
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "suggested",
                            "manual"
                        ]
                    },
                    "rotation": {
                        "type": "string",
                        "enum": [
                            "off",
                            "top1"
                        ]
                    },
                    "show_feedback_form": {
                        "type": "boolean"
                    },
                    "feedback_email": {
                        "type": "string",
                        "format": "email",
                        "nullable": true
                    },
                    "destination_link_id": {
                        "description": "Where visitors go. null, \"\" or \"page\" = the review page (default). The id of one of the page's links = every visitor of the page URL (link, QR codes, counter screen, app, tap) is counted as usual and redirected (302) straight to that button's site; the same for everyone. Refused (400 `body.destination_link_id`, reason in the message) for a disabled link or one without an address, Yelp, Glassdoor, Indeed, Trustpilot, link-only sites that take reviews only from their own bookings, and custom links to sites that are not review sites. See `links[].direct_target`.",
                        "type": "string",
                        "nullable": true
                    },
                    "links": {
                        "description": "Replaces the whole list (max 25).",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewPageLinkInput"
                        }
                    }
                },
                "type": "object"
            },
            "V1ReviewPageFeedback": {
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "page_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "rating": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 5,
                        "minimum": 1
                    },
                    "name": {
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "nullable": true
                    },
                    "message": {
                        "type": "string"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "V1ReviewPageSuggestedSite": {
                "description": "One review site of the stored ranking: rank, weight and its parts, the human reasons, and the page's link of the site.",
                "required": [
                    "rank",
                    "domain",
                    "label",
                    "weight",
                    "parts",
                    "policy",
                    "reasons",
                    "on_page",
                    "link_id",
                    "connected"
                ],
                "properties": {
                    "rank": {
                        "description": "1-based; null for policy sites (never suggested).",
                        "type": "integer",
                        "nullable": true
                    },
                    "domain": {
                        "type": "string",
                        "example": "google.com"
                    },
                    "site": {
                        "description": "Driver or catalog key of the site; null when unknown.",
                        "type": "string",
                        "nullable": true
                    },
                    "label": {
                        "type": "string",
                        "example": "Google"
                    },
                    "weight": {
                        "type": "integer",
                        "maximum": 100,
                        "minimum": 0
                    },
                    "parts": {
                        "description": "Points of each part of the weight.",
                        "properties": {
                            "ai": {
                                "type": "number"
                            },
                            "serp": {
                                "type": "number"
                            },
                            "popularity": {
                                "type": "number"
                            },
                            "impact": {
                                "type": "number"
                            },
                            "conversion": {
                                "type": "number"
                            }
                        },
                        "type": "object"
                    },
                    "conversion": {
                        "description": "What review-page visitors across Grades.com do on this site (fleet conversion prior).",
                        "properties": {
                            "rate": {
                                "type": "number",
                                "nullable": true
                            },
                            "clicks": {
                                "type": "integer"
                            },
                            "basis": {
                                "description": "`category`, `fleet`, or null (not measured).",
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "policy": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "no_solicit",
                            "employer_reviews"
                        ]
                    },
                    "policy_note": {
                        "type": "string",
                        "nullable": true
                    },
                    "summary": {
                        "description": "One human line.",
                        "type": "string"
                    },
                    "reasons": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "stats": {
                        "properties": {
                            "reviews": {
                                "type": "integer"
                            },
                            "rating": {
                                "type": "number",
                                "nullable": true
                            },
                            "latest_review_at": {
                                "type": "string",
                                "nullable": true
                            },
                            "count_only": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "ai": {
                        "description": "AI answers citing the site.",
                        "properties": {
                            "basis": {
                                "description": "`business`, `category` or null.",
                                "type": "string",
                                "nullable": true
                            },
                            "share": {
                                "type": "number"
                            },
                            "citing": {
                                "type": "integer"
                            },
                            "answers": {
                                "type": "integer"
                            },
                            "engines": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "serp": {
                        "description": "Search results mentioning the business on the site.",
                        "properties": {
                            "mentions": {
                                "type": "integer"
                            },
                            "best_position": {
                                "type": "integer",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "tier": {
                        "description": "Hub catalog tier of the domain (core, tier1, industry, tier2, aggregator); null = none.",
                        "type": "string",
                        "nullable": true
                    },
                    "on_page": {
                        "description": "true: the page has a link to this site.",
                        "type": "boolean"
                    },
                    "link_id": {
                        "description": "That link's id; null when not on the page.",
                        "type": "string",
                        "nullable": true
                    },
                    "source_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "connected": {
                        "description": "true: a source of the company is connected for this site.",
                        "type": "boolean"
                    },
                    "profile_url": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewPageSuggestions": {
                "description": "The company's stored suggested order, seen from one page.",
                "required": [
                    "version",
                    "computed_at",
                    "confirmed_at",
                    "mode",
                    "rotation",
                    "basis",
                    "order",
                    "also",
                    "sites"
                ],
                "properties": {
                    "version": {
                        "description": "Version of the weighting.",
                        "type": "integer"
                    },
                    "computed_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "confirmed_at": {
                        "description": "Last time a recomputation found the same ranking.",
                        "type": "string",
                        "format": "date-time"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "suggested",
                            "manual"
                        ]
                    },
                    "rotation": {
                        "type": "string",
                        "enum": [
                            "off",
                            "top1"
                        ]
                    },
                    "basis": {
                        "description": "How many AI answers the ranking is based on.",
                        "properties": {
                            "business_answers": {
                                "type": "integer"
                            },
                            "category_answers": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "order": {
                        "description": "Ids of the page's shown links in suggested order (policy sites excluded).",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "also": {
                        "description": "Ids of shown links of policy sites (Yelp).",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "sites": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewPageSuggestedSite"
                        }
                    }
                },
                "type": "object"
            },
            "V1ReviewPagePreview": {
                "required": [
                    "html",
                    "appearance"
                ],
                "properties": {
                    "html": {
                        "description": "The public page with the given settings (a `<base>` to this host, inert buttons), for a sandboxed iframe.",
                        "type": "string"
                    },
                    "appearance": {
                        "$ref": "#/components/schemas/V1ReviewPageAppearance"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestCampaignWriteMeta": {
                "description": "Meta of a campaign create / edit: `ignored` + `notice` only when the body sent `steps.*.sms_body` (accepted for older clients, never used); empty otherwise.",
                "properties": {
                    "ignored": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "notice": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestContactUpsertOne": {
                "description": "Answer of adding or updating one contact; `meta.created` = it was new.",
                "required": [
                    "data",
                    "meta"
                ],
                "properties": {
                    "data": {
                        "$ref": "#/components/schemas/V1ReviewRequestContact"
                    },
                    "meta": {
                        "required": [
                            "created"
                        ],
                        "properties": {
                            "created": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestContactUpsertMany": {
                "description": "Answer of `{\"contacts\": [...]}`: the contacts added or updated, counts and the errors per failed item.",
                "required": [
                    "data",
                    "meta"
                ],
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewRequestContact"
                        }
                    },
                    "meta": {
                        "required": [
                            "created",
                            "updated",
                            "failed",
                            "errors"
                        ],
                        "properties": {
                            "created": {
                                "type": "integer"
                            },
                            "updated": {
                                "type": "integer"
                            },
                            "failed": {
                                "type": "integer"
                            },
                            "errors": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "index": {
                                            "description": "Position in `contacts`.",
                                            "type": "integer"
                                        },
                                        "errors": {
                                            "description": "Messages per field.",
                                            "type": "object",
                                            "additionalProperties": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestSettings": {
                "description": "The review request settings of a business (`Settings::payload()`). `sending_allowances` only where sending allowances apply (SENDING_ALLOWANCES_STATUS).",
                "required": [
                    "sending_enabled",
                    "sms_available",
                    "entitled",
                    "paused",
                    "daily_email_cap",
                    "daily_sms_cap",
                    "min_days_between_requests"
                ],
                "properties": {
                    "sending_enabled": {
                        "description": "The global switch (REVIEW_REQUESTS_ENABLED).",
                        "type": "boolean"
                    },
                    "sms_available": {
                        "type": "boolean"
                    },
                    "entitled": {
                        "description": "The plan includes review requests of any kind.",
                        "type": "boolean"
                    },
                    "automatic_requests": {
                        "description": "The plan includes automatic requests (Pro and up).",
                        "type": "boolean"
                    },
                    "manual_requests_this_month": {
                        "properties": {
                            "used": {
                                "type": "integer"
                            },
                            "limit": {
                                "description": "null = no plan limit",
                                "type": "integer",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "paused": {
                        "type": "boolean"
                    },
                    "daily_email_cap": {
                        "type": "integer"
                    },
                    "daily_sms_cap": {
                        "type": "integer"
                    },
                    "max_daily_email_cap": {
                        "type": "integer"
                    },
                    "max_daily_sms_cap": {
                        "type": "integer"
                    },
                    "sent_today": {
                        "properties": {
                            "email": {
                                "type": "integer"
                            },
                            "sms": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "quiet_hours": {
                        "description": "Local sending window, `HH:00`.",
                        "properties": {
                            "start": {
                                "type": "string"
                            },
                            "end": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "min_days_between_requests": {
                        "type": "integer"
                    },
                    "min_days_between_requests_default": {
                        "type": "integer"
                    },
                    "min_days_between_requests_range": {
                        "properties": {
                            "min": {
                                "type": "integer"
                            },
                            "max": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "sms_consent_default_text": {
                        "type": "string"
                    },
                    "sms_consent_editable": {
                        "type": "boolean"
                    },
                    "sms_consent_required": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "sms_sender": {
                        "type": "string"
                    },
                    "sms_templates": {
                        "description": "The fixed Grades.com texts, one per step.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "timezone": {
                        "type": "string"
                    },
                    "from_address": {
                        "type": "string"
                    },
                    "postal_address": {
                        "description": "null = no address (email cannot be sent)",
                        "type": "string",
                        "nullable": true
                    },
                    "can_send_email": {
                        "type": "boolean"
                    },
                    "merge_fields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "default_campaign": {
                        "description": "null before the first request; `paused` = requests wait until it is resumed.",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "active",
                                    "paused",
                                    "archived"
                                ]
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "sending_allowances": {
                        "description": "This month's emails and texts against the plan's allowance, extra sending, held requests and the closed months (docs/review-requests.md \"Sending allowances\").",
                        "properties": {
                            "month": {
                                "type": "string"
                            },
                            "resets_at": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "emails": {
                                "$ref": "#/components/schemas/V1ReviewRequestChannelUsage"
                            },
                            "texts": {
                                "$ref": "#/components/schemas/V1ReviewRequestChannelUsage"
                            },
                            "extra_sending": {
                                "description": "`can_change` only when the viewer is known.",
                                "properties": {
                                    "enabled": {
                                        "type": "boolean"
                                    },
                                    "changed_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "changed_by": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "cap_usd": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "cap_suggestion_usd": {
                                        "type": "integer"
                                    },
                                    "cap_min_usd": {
                                        "type": "integer"
                                    },
                                    "cap_max_usd": {
                                        "type": "integer"
                                    },
                                    "spent_usd": {
                                        "type": "number"
                                    },
                                    "available": {
                                        "type": "boolean"
                                    },
                                    "unavailable_reason": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "terms": {
                                        "description": "`emails` / `texts`: `{block_size, block_price_usd}`.",
                                        "type": "object",
                                        "additionalProperties": true
                                    },
                                    "can_change": {
                                        "type": "boolean"
                                    }
                                },
                                "type": "object"
                            },
                            "held": {
                                "properties": {
                                    "count": {
                                        "type": "integer"
                                    },
                                    "sending_allowance_used": {
                                        "type": "integer"
                                    },
                                    "extra_sending_cap_reached": {
                                        "type": "integer"
                                    }
                                },
                                "type": "object"
                            },
                            "history": {
                                "description": "Closed months, newest first: `{month, emails, texts, charge}`.",
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestChannelUsage": {
                "description": "This month's messages of one channel against the plan's allowance.",
                "properties": {
                    "used": {
                        "type": "integer"
                    },
                    "allowance": {
                        "type": "integer"
                    },
                    "remaining": {
                        "type": "integer"
                    },
                    "overage": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestStats": {
                "description": "Review request stats of the requests created in the window (`Stats::report()`).",
                "required": [
                    "totals",
                    "channels",
                    "campaigns"
                ],
                "properties": {
                    "totals": {
                        "$ref": "#/components/schemas/V1ReviewRequestStatsCounts"
                    },
                    "channels": {
                        "description": "Message counts per channel.",
                        "properties": {
                            "email": {
                                "$ref": "#/components/schemas/V1ReviewRequestChannelStats"
                            },
                            "sms": {
                                "$ref": "#/components/schemas/V1ReviewRequestChannelStats"
                            }
                        },
                        "type": "object"
                    },
                    "campaigns": {
                        "description": "Per campaign (archived ones without requests left out): `id`, `name` and the request counts.",
                        "type": "array",
                        "items": {
                            "allOf": [
                                {
                                    "properties": {
                                        "id": {
                                            "type": "string",
                                            "format": "uuid"
                                        },
                                        "name": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                },
                                {
                                    "$ref": "#/components/schemas/V1ReviewRequestStatsCounts"
                                }
                            ]
                        }
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestStatsCounts": {
                "description": "Request-level counts; rates are of `sent` (null when nothing was sent).",
                "properties": {
                    "requests": {
                        "type": "integer"
                    },
                    "sent": {
                        "type": "integer"
                    },
                    "delivered": {
                        "type": "integer"
                    },
                    "opened": {
                        "type": "integer"
                    },
                    "clicked": {
                        "type": "integer"
                    },
                    "visited": {
                        "type": "integer"
                    },
                    "reviewed": {
                        "type": "integer"
                    },
                    "opted_out": {
                        "type": "integer"
                    },
                    "bounced": {
                        "type": "integer"
                    },
                    "failed": {
                        "type": "integer"
                    },
                    "skipped": {
                        "type": "integer"
                    },
                    "click_rate": {
                        "type": "number",
                        "nullable": true
                    },
                    "review_rate": {
                        "type": "number",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestSendOne": {
                "description": "Answer of a send to one contact: the request with `held`; `meta.existing` = the same `external_ref` answered the existing request.",
                "required": [
                    "data",
                    "meta"
                ],
                "properties": {
                    "data": {
                        "$ref": "#/components/schemas/V1ReviewRequest"
                    },
                    "meta": {
                        "required": [
                            "existing"
                        ],
                        "properties": {
                            "existing": {
                                "type": "boolean"
                            },
                            "held": {
                                "$ref": "#/components/schemas/V1ReviewRequestHold"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestSendMany": {
                "description": "Answer of a send to a list (`contacts`) or a tag: the requests made or found, with counts and the skipped items. `held_back` only where sending allowances apply.",
                "required": [
                    "data",
                    "meta"
                ],
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewRequest"
                        }
                    },
                    "meta": {
                        "required": [
                            "created",
                            "existing",
                            "skipped"
                        ],
                        "properties": {
                            "created": {
                                "type": "integer"
                            },
                            "existing": {
                                "type": "integer"
                            },
                            "skipped": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "index": {
                                            "description": "Position in `contacts`; null for a tag.",
                                            "type": "integer",
                                            "nullable": true
                                        },
                                        "contact_id": {
                                            "type": "string",
                                            "format": "uuid",
                                            "nullable": true
                                        },
                                        "reason": {
                                            "description": "A refusal code (`opted_out`, `recently_requested`, ...), `unknown_contact`, `invalid_contact`, `plan_limit` or `sending_allowance_used`.",
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "held": {
                                "$ref": "#/components/schemas/V1ReviewRequestHold"
                            },
                            "held_back": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestChannelStats": {
                "description": "Message counts of one channel.",
                "properties": {
                    "sent": {
                        "type": "integer"
                    },
                    "delivered": {
                        "type": "integer"
                    },
                    "opened": {
                        "type": "integer"
                    },
                    "clicked": {
                        "type": "integer"
                    },
                    "bounced": {
                        "type": "integer"
                    },
                    "failed": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1ReviewTag": {
                "description": "A tag definition.",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "color": {
                        "description": "A color token (`meta.colors` of the list).",
                        "type": "string"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "manual",
                            "auto"
                        ]
                    },
                    "group": {
                        "type": "string",
                        "enum": [
                            "custom",
                            "topic",
                            "flag",
                            "service"
                        ]
                    },
                    "description": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "review_count": {
                        "description": "Reviews carrying it, removed reviews left out (in the tag list and, as 0, on create).",
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1ReviewTagState": {
                "description": "A review's tags and sentiment after a change.",
                "properties": {
                    "review": {
                        "description": "The review uuid.",
                        "type": "string",
                        "format": "uuid"
                    },
                    "tags": {
                        "description": "Live tags, manual first, then by name.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "slug": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "color": {
                                    "type": "string"
                                },
                                "kind": {
                                    "type": "string",
                                    "enum": [
                                        "manual",
                                        "auto"
                                    ]
                                },
                                "group": {
                                    "type": "string",
                                    "enum": [
                                        "custom",
                                        "topic",
                                        "flag",
                                        "service"
                                    ]
                                },
                                "source": {
                                    "type": "string",
                                    "enum": [
                                        "manual",
                                        "auto",
                                        "service"
                                    ]
                                },
                                "confidence": {
                                    "type": "number",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "sentiment": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "positive",
                            "neutral",
                            "negative",
                            "mixed"
                        ]
                    }
                },
                "type": "object"
            },
            "V1ShopifyPrivacyRequest": {
                "required": [
                    "id",
                    "shop",
                    "topic",
                    "status",
                    "contacts_found",
                    "contacts_redacted",
                    "report_available",
                    "report_expires_at",
                    "completed_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "shop": {
                        "type": "string",
                        "example": "wrenfield-dental.myshopify.com"
                    },
                    "topic": {
                        "type": "string",
                        "enum": [
                            "customers/data_request",
                            "customers/redact",
                            "shop/redact"
                        ]
                    },
                    "status": {
                        "description": "E.g. `ready`, `completed`, `expired`.",
                        "type": "string"
                    },
                    "contacts_found": {
                        "type": "integer"
                    },
                    "contacts_redacted": {
                        "type": "integer"
                    },
                    "report_available": {
                        "type": "boolean"
                    },
                    "report_expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "completed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ShopifyPrivacyReport": {
                "description": "What Grades.com holds for a Shopify customer (customers/data_request), for the business to send on.",
                "required": [
                    "shop",
                    "customer_id",
                    "generated_at",
                    "contacts",
                    "review_requests",
                    "order_events"
                ],
                "properties": {
                    "shop": {
                        "type": "string"
                    },
                    "customer_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "generated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "contacts": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "name": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "email": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "phone": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "tags": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    },
                                    "nullable": true
                                },
                                "source": {
                                    "type": "string"
                                },
                                "email_consent_source": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "email_consent_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "created_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "deleted_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "review_requests": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "id": {
                                    "type": "string",
                                    "format": "uuid"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "trigger": {
                                    "type": "string"
                                },
                                "stop_reason": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "created_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "order_events": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "order_id": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "kind": {
                                    "type": "string"
                                },
                                "outcome": {
                                    "type": "string"
                                },
                                "reason": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "occurred_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1ShowcaseInput": {
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 80
                    },
                    "style": {
                        "type": "string",
                        "enum": [
                            "light",
                            "dark",
                            "auto"
                        ]
                    },
                    "count": {
                        "type": "integer",
                        "maximum": 50,
                        "minimum": 1
                    },
                    "min_rating": {
                        "type": "integer",
                        "maximum": 5,
                        "minimum": 1
                    },
                    "min_length": {
                        "type": "integer",
                        "maximum": 2000,
                        "minimum": 0
                    },
                    "max_length": {
                        "type": "integer",
                        "maximum": 5000,
                        "minimum": 40
                    },
                    "topic": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 80
                    },
                    "sites": {
                        "description": "Site keys or drivers, as a list or a comma-separated string; empty = every eligible site.",
                        "oneOf": [
                            {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "maxLength": 40
                                }
                            },
                            {
                                "type": "string"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "max_age_days": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 3650,
                        "minimum": 1
                    },
                    "language": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "en",
                            "es",
                            "fr",
                            "pt",
                            "de",
                            "it"
                        ]
                    },
                    "seed": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 40
                    },
                    "tags": {
                        "description": "Review tag slugs (any of them), as a list or a comma-separated string.",
                        "oneOf": [
                            {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "maxLength": 64
                                }
                            },
                            {
                                "type": "string"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "yelp_consent": {
                        "description": "true = the caller confirms Yelp's terms for a showcase whose `sites` name Yelp (recorded on the showcase).",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1SiteRequestResult": {
                "required": [
                    "outcome",
                    "domain",
                    "request"
                ],
                "properties": {
                    "outcome": {
                        "description": "`connected` (the catalog serves the site: the source was connected), `already_connected`, or `requested` (recorded; the site is in the demand queue).",
                        "type": "string",
                        "enum": [
                            "connected",
                            "already_connected",
                            "requested"
                        ]
                    },
                    "domain": {
                        "type": "string",
                        "example": "vagaro.com"
                    },
                    "label": {
                        "type": "string",
                        "example": "Vagaro",
                        "nullable": true
                    },
                    "request": {
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "url": {
                                "type": "string"
                            },
                            "created_at": {
                                "type": "string",
                                "format": "date-time"
                            }
                        },
                        "type": "object"
                    },
                    "source": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1Source"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "candidate": {
                        "description": "The demand-queue entry (`requested` only).",
                        "properties": {
                            "domain": {
                                "type": "string"
                            },
                            "label": {
                                "type": "string",
                                "nullable": true
                            },
                            "status": {
                                "type": "string"
                            },
                            "demand_customers": {
                                "type": "integer"
                            },
                            "demand_requests": {
                                "type": "integer"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "tracking": {
                        "description": "`requested` only: the tracked request, due two weeks after it was made (`GET .../sources/requests`).",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "status": {
                                "type": "string"
                            },
                            "requested_at": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "due_at": {
                                "type": "string",
                                "format": "date-time"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SourceReplyApi": {
                "required": [
                    "source",
                    "available",
                    "connected",
                    "key_hint",
                    "business_user_id",
                    "verified_at",
                    "requirements"
                ],
                "properties": {
                    "source": {
                        "type": "string",
                        "example": "trustpilot"
                    },
                    "available": {
                        "description": "Whether replies on this site can be posted through its API at all (the platform switch).",
                        "type": "boolean"
                    },
                    "connected": {
                        "description": "Whether the company stored credentials: approved (and auto-posted) replies are then published on the site through its API.",
                        "type": "boolean"
                    },
                    "key_hint": {
                        "type": "string",
                        "example": "…a1b2",
                        "nullable": true
                    },
                    "business_user_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "verified_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "requirements": {
                        "description": "What the company needs on the site.",
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1ReviewStrengths": {
                "required": [
                    "available",
                    "reason",
                    "listing_id",
                    "profile_url",
                    "strengths",
                    "basis"
                ],
                "properties": {
                    "available": {
                        "type": "boolean"
                    },
                    "reason": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "no_listing",
                            "no_themes"
                        ]
                    },
                    "listing_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "profile_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "strengths": {
                        "description": "Most mentioned first.",
                        "type": "array",
                        "items": {
                            "required": [
                                "label",
                                "attribute",
                                "summary",
                                "mentions",
                                "quote",
                                "cited_reviews",
                                "cited_readable"
                            ],
                            "properties": {
                                "label": {
                                    "type": "string"
                                },
                                "attribute": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "summary": {
                                    "type": "string"
                                },
                                "mentions": {
                                    "type": "integer"
                                },
                                "quote": {
                                    "description": "The profile's excerpt; null where the profile shows none.",
                                    "required": [
                                        "text",
                                        "author",
                                        "site",
                                        "date",
                                        "date_display",
                                        "review_uuid"
                                    ],
                                    "properties": {
                                        "text": {
                                            "type": "string"
                                        },
                                        "author": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "site": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "date": {
                                            "type": "string",
                                            "format": "date",
                                            "nullable": true
                                        },
                                        "date_display": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "review_uuid": {
                                            "type": "string",
                                            "format": "uuid",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object",
                                    "nullable": true
                                },
                                "cited_reviews": {
                                    "description": "Uuids of the cited reviews the caller can read, newest first (at most 20).",
                                    "type": "array",
                                    "items": {
                                        "type": "string",
                                        "format": "uuid"
                                    }
                                },
                                "cited_readable": {
                                    "description": "How many cited reviews are readable.",
                                    "type": "integer"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "basis": {
                        "description": "The sample the themes were written from; null without themes.",
                        "required": [
                            "sites",
                            "excluded",
                            "from",
                            "to",
                            "reviews",
                            "window",
                            "line",
                            "generated_at"
                        ],
                        "properties": {
                            "sites": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "excluded": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "from": {
                                "type": "string",
                                "nullable": true
                            },
                            "to": {
                                "type": "string",
                                "nullable": true
                            },
                            "reviews": {
                                "type": "integer"
                            },
                            "window": {
                                "oneOf": [
                                    {
                                        "type": "integer"
                                    },
                                    {
                                        "type": "string"
                                    },
                                    {
                                        "type": "object",
                                        "nullable": true,
                                        "enum": [
                                            null
                                        ]
                                    }
                                ]
                            },
                            "line": {
                                "type": "string",
                                "nullable": true
                            },
                            "generated_at": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1TeamMember": {
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string"
                    },
                    "phone": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "pending"
                        ]
                    },
                    "role": {
                        "description": "The role at this company (the strongest that reaches it). `super_admin` = owner, `user` = legacy member.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "owner",
                            "super_admin",
                            "admin",
                            "approver",
                            "reviewer",
                            "viewer",
                            "user"
                        ]
                    },
                    "role_label": {
                        "type": "string",
                        "nullable": true
                    },
                    "role_summary": {
                        "type": "string",
                        "nullable": true
                    },
                    "scope": {
                        "description": "`all`: the HQ and every location; `company`: this company only; `locations`: the listed companies.",
                        "type": "string",
                        "enum": [
                            "all",
                            "company",
                            "locations"
                        ]
                    },
                    "all_locations": {
                        "type": "boolean"
                    },
                    "memberships": {
                        "description": "Every row: company, role, all_locations, status, via (`member`, or `hq` for an HQ row that reaches this location).",
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "abilities": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "settings.edit",
                                "settings.lock",
                                "agent.settings.edit",
                                "members.invite",
                                "sources.connect",
                                "actions.approve",
                                "actions.reject",
                                "reviews.reply",
                                "reviews.hide",
                                "reviews.flag",
                                "billing.manage",
                                "reports.view"
                            ]
                        }
                    },
                    "manageable": {
                        "description": "Whether the caller may change or remove this member.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1WidgetMeta": {
                "description": "`meta` of the company widget endpoint (the dashboard's widget builder).",
                "properties": {
                    "options": {
                        "description": "The resolved options.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "limits": {
                        "description": "The plan's Review Showcase limits (`enabled`, `plan`, `max_reviews`, `max_showcases`, `refresh_minutes`).",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "access": {
                        "description": "What the plan allows.",
                        "properties": {
                            "enabled": {
                                "type": "boolean"
                            },
                            "free": {
                                "description": "The free widget of a claimed listing.",
                                "type": "boolean"
                            },
                            "plan": {
                                "type": "string"
                            },
                            "presets": {
                                "description": "The presets allowed; null = all.",
                                "type": "array",
                                "items": {
                                    "type": "string"
                                },
                                "nullable": true
                            },
                            "sites": {
                                "description": "The sites allowed; null = all.",
                                "type": "array",
                                "items": {
                                    "type": "string"
                                },
                                "nullable": true
                            },
                            "max_reviews": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "embed": {
                        "$ref": "#/components/schemas/V1WidgetEmbed"
                    },
                    "available_sites": {
                        "description": "The review sites the widget can name, most reviews first.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "count": {
                                    "type": "integer"
                                },
                                "average": {
                                    "type": "number"
                                },
                                "average_label": {
                                    "type": "string"
                                },
                                "icon_url": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "presets": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "pill",
                                "strip",
                                "carousel",
                                "grid",
                                "list",
                                "masonry",
                                "spotlight",
                                "summary",
                                "wall",
                                "video",
                                "badge",
                                "popup",
                                "tab",
                                "button"
                            ]
                        }
                    },
                    "preset_info": {
                        "description": "Each preset with its label, availability, options, defaults and review counts (keyed by `key`).",
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "empty_reason": {
                        "description": "Why the widget shows nothing; null when it shows something.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "no_video_reviews",
                            "no_reviews",
                            "no_rating",
                            "no_review_page"
                        ]
                    },
                    "tags": {
                        "properties": {
                            "available": {
                                "description": "Review tags on at least one review (`slug`, `name`, `group`, `count`).",
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            }
                        },
                        "type": "object"
                    },
                    "filter": {
                        "description": "What narrows the reviews and the notice the dashboard shows the owner.",
                        "properties": {
                            "active": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "notice": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "accent_source": {
                        "type": "string",
                        "enum": [
                            "snippet",
                            "review_page",
                            "default"
                        ]
                    },
                    "v2": {
                        "description": "Widgets v2 only (while the gate admits the company): visitor params, custom CSS, AI summary state.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "rendered": {
                        "description": "`include=html` only.",
                        "properties": {
                            "html": {
                                "description": "The hosted widget page.",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "AIReplyForbiddenResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "AI reply is not allowed for this review."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "AIReplyLimitExceededResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Monthly AI reply limit reached."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "AIReplyServiceBusyResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "AI reply service is busy, please try again in a moment."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "AISettingsIncompleteResponse": {
                "required": [
                    "message",
                    "code",
                    "missing"
                ],
                "properties": {
                    "message": {
                        "type": "string",
                        "example": "AI Settings are incomplete."
                    },
                    "code": {
                        "type": "string",
                        "example": "ai_settings_incomplete"
                    },
                    "missing": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "business_description",
                                "tone",
                                "industry"
                            ]
                        }
                    }
                },
                "type": "object"
            },
            "GeminiApiErrorResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "AI service is temporarily unavailable."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "GenerateAIReply": {
                "required": [
                    "reply"
                ],
                "properties": {
                    "reply": {
                        "type": "string",
                        "example": "So glad the team had everything ready on time."
                    },
                    "needs_review": {
                        "description": "True when the draft still breaks one of the reply rules after one rewrite (or the rules check could not run): read and edit it before posting.",
                        "type": "boolean"
                    },
                    "failed_rules": {
                        "description": "The rules it still breaks: staff_name, clinical_details, patient_relationship, review_solicitation, signature, wrong_language, contact_details, breaks_rules, rules_check_unavailable.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "language": {
                        "description": "The draft's language (ISO 639-1; the business's reply language setting decides it), null when unknown.",
                        "type": "string",
                        "nullable": true
                    },
                    "draft_en": {
                        "description": "Machine translation of a non-English draft into English (\"Translated by AI\"); never post it.",
                        "type": "string",
                        "nullable": true
                    },
                    "draft_translation": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1Translation"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "ApiKey": {
                "required": [
                    "id",
                    "name",
                    "integration",
                    "prefix",
                    "abilities",
                    "companies",
                    "created_via",
                    "created_by_client",
                    "last_used_at",
                    "expires_at",
                    "created_at"
                ],
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 12
                    },
                    "name": {
                        "type": "string",
                        "example": "Zapier",
                        "maxLength": 100
                    },
                    "integration": {
                        "description": "The integration the key was made for (the dashboard's guided \"Connect\" flow); null = made by hand, or before 2026-11.",
                        "type": "string",
                        "example": "zapier",
                        "nullable": true,
                        "enum": [
                            "zapier",
                            "make",
                            "n8n",
                            "sheets",
                            "looker",
                            "woocommerce",
                            "reporting",
                            "custom"
                        ]
                    },
                    "prefix": {
                        "description": "First characters of the key, for telling keys apart.",
                        "type": "string",
                        "example": "gk_live_Ab3x"
                    },
                    "abilities": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "reviews:read",
                                "reviews:write",
                                "companies:read",
                                "companies:write",
                                "directory:read"
                            ]
                        }
                    },
                    "companies": {
                        "description": "Uuids of the businesses the key is limited to; null = every business of its owner.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uuid"
                        },
                        "nullable": true
                    },
                    "url_key": {
                        "description": "A reporting URL key (prefix `gk_live_url_`, `reviews:read` only): the only kind of key the reports API accepts as `?key=` (www/docs/reports.md \"Key in the URL\"). Shown as \"URL key\" in key lists.",
                        "type": "boolean"
                    },
                    "created_via": {
                        "description": "How the key was made: dashboard, mcp (an AI app connected to the Grades.com MCP server) or api; null = before 2026-11.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "dashboard",
                            "mcp",
                            "api"
                        ]
                    },
                    "created_by_client": {
                        "description": "The AI app that made the key (its registered OAuth client name), e.g. \"Claude\".",
                        "type": "string",
                        "example": "Claude",
                        "nullable": true
                    },
                    "last_used_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "CreatedApiKey": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/ApiKey"
                    },
                    {
                        "required": [
                            "key"
                        ],
                        "properties": {
                            "key": {
                                "description": "The secret key. Shown only in this response; store it securely.",
                                "type": "string",
                                "example": "gk_live_Ab3xR0x9yTqZ2v7mN1kP5sW8cD4fG6hJ0lQ3eU9a"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "AuthorizationErrorResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Unauthenticated."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "Entitlements": {
                "description": "What the plan includes. A null limit is no plan limit (AI drafts: the global fair-use ceiling still applies).",
                "properties": {
                    "sources": {
                        "description": "Connectable source drivers, or \"*\" for all.",
                        "oneOf": [
                            {
                                "type": "string",
                                "enum": [
                                    "*"
                                ]
                            },
                            {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        ]
                    },
                    "refresh_cadence": {
                        "description": "Deprecated, informational only: reviews are collected the same way on every plan (Google and Facebook every couple of hours, most other sites daily), so it is not a plan difference and the plan comparison no longer has a row for it.",
                        "type": "string",
                        "enum": [
                            "weekly",
                            "daily",
                            "hourly"
                        ]
                    },
                    "max_users": {
                        "type": "integer",
                        "nullable": true
                    },
                    "max_api_keys": {
                        "description": "Per user.",
                        "type": "integer",
                        "nullable": true
                    },
                    "ai_drafts_per_month": {
                        "description": "AI reply drafts per location a calendar month, a quiet fair-use number (Starter 25); null = no plan allowance, the global ceiling (GEMINI_LIMIT_COUNT, 1,000 in production) still caps it.",
                        "type": "integer",
                        "nullable": true
                    },
                    "replies_posted_per_month": {
                        "description": "Replies posted through Grades.com (to a review site or a Review on Grades.com) per location a calendar month, whoever wrote them; an edit of a reply counted this month and a reply only saved do not count. Starter 5, null = no plan limit.",
                        "type": "integer",
                        "nullable": true
                    },
                    "manual_review_requests_per_month": {
                        "description": "Review requests a person sends by email (one contact, a list, an uploaded file) per location a calendar month: Starter 50, null = no plan limit. Automatic requests and SMS need the feature `review_requests`.",
                        "type": "integer",
                        "nullable": true
                    },
                    "ai_probe_cadence_days": {
                        "description": "Days between scheduled AI Reputation probes: Starter 30, Pro 7, Premium 1 (null: none). While billing is not configured: AI_PROBE_DEFAULT_CADENCE_DAYS (7).",
                        "type": "integer",
                        "nullable": true
                    },
                    "ai_probe_cadence_label": {
                        "description": "The cadence in words: daily, weekly, monthly or \"every N days\" (null: none).",
                        "type": "string",
                        "nullable": true
                    },
                    "agent_features": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "policy_check",
                                "reply_drafts",
                                "auto_positive",
                                "flag_drafts",
                                "browser_automation"
                            ]
                        }
                    },
                    "features": {
                        "description": "Product features of the plan (config/plans.php `features`).",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "listing_edits",
                                "badges",
                                "review_page",
                                "alerts_digest",
                                "mcp_api",
                                "hq_rollup",
                                "review_radar",
                                "source_discovery",
                                "ai_reputation",
                                "direct_reviews",
                                "review_showcase",
                                "widgets",
                                "review_requests_manual",
                                "bigquery_export",
                                "webhooks",
                                "competitor_map",
                                "competitor_alerts",
                                "ai_reputation_alerts",
                                "group_alerts",
                                "auto_reply_all",
                                "review_requests",
                                "removal_filing"
                            ]
                        }
                    },
                    "history_days": {
                        "type": "integer",
                        "nullable": true
                    },
                    "white_label_mcp": {
                        "type": "boolean"
                    },
                    "public_reviews_api": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "Billing": {
                "description": "Billing state of a location. `mode: unconfigured` (no Stripe keys yet) means every location has the Pro plan and the billing actions answer 409.",
                "properties": {
                    "company": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "mode": {
                        "type": "string",
                        "enum": [
                            "stripe",
                            "unconfigured",
                            "directory"
                        ]
                    },
                    "plan": {
                        "type": "string",
                        "enum": [
                            "starter",
                            "pro",
                            "premium",
                            "free_locked",
                            "directory",
                            "claimed"
                        ]
                    },
                    "plan_name": {
                        "type": "string",
                        "example": "Pro"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "trialing",
                            "active",
                            "past_due",
                            "canceled",
                            "expired",
                            "unconfigured",
                            "directory",
                            "claimed"
                        ]
                    },
                    "source": {
                        "description": "Where the plan comes from.",
                        "type": "string",
                        "enum": [
                            "subscription",
                            "agency",
                            "hq",
                            "agency_grace",
                            "trial",
                            "none",
                            "unconfigured",
                            "directory",
                            "claimed"
                        ]
                    },
                    "locked": {
                        "description": "Read-only: writes answer 402 `billing_locked`.",
                        "type": "boolean"
                    },
                    "lock_at": {
                        "description": "When the location locks (trial end, past_due grace end) or locked.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "parsing_stops_at": {
                        "description": "Locked locations: when reviews stop refreshing.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "trial_ends_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "renews_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "cancel_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "interval": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "monthly",
                            "yearly"
                        ]
                    },
                    "quantity": {
                        "description": "Billed extra locations of the business (the first location is in the base price).",
                        "type": "integer",
                        "nullable": true
                    },
                    "inherited_from": {
                        "description": "The HQ whose plan this location uses.",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "hq_company": {
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "locations": {
                        "description": "Locations attached to this HQ.",
                        "type": "integer"
                    },
                    "business_locations": {
                        "description": "Locations of the business (its HQ included); the volume bands count these.",
                        "type": "integer"
                    },
                    "promotion_code_pending": {
                        "type": "boolean"
                    },
                    "entitlements": {
                        "$ref": "#/components/schemas/Entitlements"
                    },
                    "usage": {
                        "properties": {
                            "ai_drafts": {
                                "description": "This calendar month: `used`, `limit` (after the global ceiling) and `plan_limit` (the fair-use allowance of the plan, null = no plan allowance: the global ceiling still caps it).",
                                "type": "object"
                            },
                            "replies_posted": {
                                "description": "This calendar month: `used` (replies posted through Grades.com, one per review), `limit` and `plan_limit` (null = no limit).",
                                "properties": {
                                    "used": {
                                        "type": "integer"
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "plan_limit": {
                                        "type": "integer",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            },
                            "review_requests_manual": {
                                "description": "This calendar month: `used` (review requests sent by hand) and `limit` (null = no plan limit).",
                                "properties": {
                                    "used": {
                                        "type": "integer"
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            },
                            "users": {
                                "type": "object"
                            },
                            "api_keys": {
                                "description": "The caller's keys.",
                                "type": "object"
                            },
                            "sources": {
                                "type": "object"
                            }
                        },
                        "type": "object"
                    },
                    "portal_available": {
                        "type": "boolean"
                    },
                    "checkout_available": {
                        "type": "boolean"
                    },
                    "plans": {
                        "description": "Plans and the intervals that can be bought.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "plan": {
                                    "type": "string",
                                    "enum": [
                                        "starter",
                                        "pro",
                                        "premium"
                                    ]
                                },
                                "name": {
                                    "type": "string"
                                },
                                "tagline": {
                                    "type": "string"
                                },
                                "intervals": {
                                    "type": "array",
                                    "items": {
                                        "type": "string",
                                        "enum": [
                                            "monthly",
                                            "yearly"
                                        ]
                                    }
                                },
                                "entitlements": {
                                    "$ref": "#/components/schemas/Entitlements"
                                },
                                "price": {
                                    "description": "List price of the business (first location included), whole US dollars; `yearly` is per year.",
                                    "properties": {
                                        "currency": {
                                            "type": "string",
                                            "example": "usd"
                                        },
                                        "monthly": {
                                            "type": "integer",
                                            "example": 149,
                                            "nullable": true
                                        },
                                        "yearly": {
                                            "type": "integer",
                                            "example": 1490,
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                },
                                "extra_location_price": {
                                    "description": "List price of each extra location in the first band, whole US dollars.",
                                    "properties": {
                                        "currency": {
                                            "type": "string",
                                            "example": "usd"
                                        },
                                        "monthly": {
                                            "type": "integer",
                                            "example": 75,
                                            "nullable": true
                                        },
                                        "yearly": {
                                            "type": "integer",
                                            "example": 750,
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                },
                                "per_location": {
                                    "description": "Shown as a price per location (Starter: the base price is one location).",
                                    "type": "boolean"
                                },
                                "location_tiers": {
                                    "description": "Volume bands by location number (graduated), whole US dollars per location.",
                                    "type": "array",
                                    "items": {
                                        "properties": {
                                            "from": {
                                                "type": "integer"
                                            },
                                            "to": {
                                                "type": "integer",
                                                "nullable": true
                                            },
                                            "monthly": {
                                                "type": "integer"
                                            },
                                            "yearly": {
                                                "type": "integer"
                                            }
                                        },
                                        "type": "object"
                                    }
                                }
                            },
                            "type": "object"
                        }
                    },
                    "claimed_plan": {
                        "description": "A claimed directory listing without a plan (not purchasable), for comparison.",
                        "properties": {
                            "plan": {
                                "type": "string",
                                "example": "claimed"
                            },
                            "name": {
                                "type": "string",
                                "example": "Claimed listing"
                            },
                            "entitlements": {
                                "$ref": "#/components/schemas/Entitlements"
                            }
                        },
                        "type": "object"
                    },
                    "quote": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/BillingQuote"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ],
                        "description": "What the business pays on its current plan (null when it is not on a purchasable plan)."
                    },
                    "quotes": {
                        "description": "What the business pays on each plan: `starter`, `pro`, `premium`.",
                        "type": "object",
                        "additionalProperties": {
                            "$ref": "#/components/schemas/BillingQuote"
                        }
                    },
                    "comparison": {
                        "description": "The plan comparison: one row per line of the lineup (`replies_posted`, `review_requests_manual`, `review_requests`, `flag_drafts`, ...), each plan's value a bool, an int, null (no plan limit, see the row's `note`) or a short text. For a business with sending allowances (SENDING_ALLOWANCES_STATUS) `review_requests_manual` is each plan's monthly review request emails and a `review_requests_sms` row (texts) follows; a plan without any is false.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "key": {
                                    "type": "string",
                                    "example": "competitor_map"
                                },
                                "label": {
                                    "type": "string",
                                    "example": "Competitor Map"
                                },
                                "values": {
                                    "type": "object"
                                },
                                "coming_soon": {
                                    "type": "boolean"
                                },
                                "note": {
                                    "type": "string",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "billing_terms": {
                        "description": "Trial lengths and the refund policy: monthly plans cancel at period end without a refund, yearly plans get a pro-rated refund within `yearly_prorated_refund_days` of purchase or renewal.",
                        "properties": {
                            "trial_days": {
                                "type": "integer",
                                "example": 14
                            },
                            "smartsites_trial_months": {
                                "type": "integer",
                                "example": 3
                            },
                            "monthly_refunds": {
                                "type": "boolean",
                                "example": false
                            },
                            "yearly_prorated_refund_days": {
                                "type": "integer",
                                "example": 30
                            }
                        },
                        "type": "object"
                    },
                    "smartsites_offer": {
                        "description": "Only for businesses with the Client Hub offer (Hub-provisioned): Premium free for `trial_months`, then `discount_percent` off.",
                        "properties": {
                            "eligible": {
                                "type": "boolean"
                            },
                            "plan": {
                                "type": "string",
                                "example": "premium"
                            },
                            "trial_months": {
                                "type": "integer",
                                "example": 3
                            },
                            "discount_percent": {
                                "type": "integer",
                                "example": 25
                            },
                            "trial_ends_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "founder_rate": {
                        "description": "The Founder's rate (docs/billing.md \"4d. Founder's rate\"); null unless the offer's gate admits the business. `open`: a checkout of a regular plan now gets `discount_percent` off for as long as the subscription stays active. `member`: the business has the rate (`number` = its place, `since` = its first payment). `ended_at` / `end_reason` (`canceled`, `lapsed`, `downgraded`, `not_admitted`): when and why it ended; it does not come back. `ends_on_downgrade`: moving to a lower plan ends it (the same plan, upgrades, interval switches and location changes keep it).",
                        "properties": {
                            "open": {
                                "type": "boolean"
                            },
                            "discount_percent": {
                                "type": "integer",
                                "example": 25
                            },
                            "member": {
                                "type": "boolean"
                            },
                            "number": {
                                "type": "integer",
                                "example": 12,
                                "nullable": true
                            },
                            "since": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "ended_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "end_reason": {
                                "type": "string",
                                "example": "downgraded",
                                "nullable": true
                            },
                            "ends_on_downgrade": {
                                "type": "boolean",
                                "example": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "payment_method": {
                        "description": "The card on file (brand, last 4 digits, expiry only), or null. Saved through Stripe Checkout (setup mode, `POST .../billing/setup-link`); card numbers never reach Grades.",
                        "properties": {
                            "brand": {
                                "type": "string",
                                "example": "visa",
                                "nullable": true
                            },
                            "last4": {
                                "type": "string",
                                "example": "4242"
                            },
                            "exp_month": {
                                "type": "integer",
                                "example": 4,
                                "nullable": true
                            },
                            "exp_year": {
                                "type": "integer",
                                "example": 2030,
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "card_on_file": {
                        "type": "boolean"
                    },
                    "trial": {
                        "description": "While a trial runs: when it ends, whether a card is on file and the plan it continues as (null: none chosen, the location locks when the trial ends).",
                        "properties": {
                            "ends_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "card_on_file": {
                                "type": "boolean"
                            },
                            "continues_as": {
                                "type": "object",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "pending_change": {
                        "description": "A confirmed change that waits: `status` awaiting_payment_method (completes once a card is saved) or scheduled (a downgrade at `effective_at`).",
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "plan": {
                                "type": "string",
                                "enum": [
                                    "starter",
                                    "pro",
                                    "premium"
                                ]
                            },
                            "plan_name": {
                                "type": "string"
                            },
                            "interval": {
                                "type": "string",
                                "enum": [
                                    "monthly",
                                    "yearly"
                                ]
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "awaiting_payment_method",
                                    "scheduled"
                                ]
                            },
                            "kind": {
                                "type": "string"
                            },
                            "effective": {
                                "type": "string",
                                "enum": [
                                    "now",
                                    "period_end",
                                    "trial_end"
                                ]
                            },
                            "effective_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "created_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "change_options": {
                        "description": "Every plan and interval the business may move to (the current one left out), with when it takes effect and whether a card must be added first. Empty while billing is unconfigured or `change_blocked`.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "plan": {
                                    "type": "string",
                                    "enum": [
                                        "starter",
                                        "pro",
                                        "premium"
                                    ]
                                },
                                "plan_name": {
                                    "type": "string"
                                },
                                "interval": {
                                    "type": "string",
                                    "enum": [
                                        "monthly",
                                        "yearly"
                                    ]
                                },
                                "kind": {
                                    "type": "string",
                                    "enum": [
                                        "start",
                                        "upgrade",
                                        "downgrade",
                                        "switch_interval"
                                    ]
                                },
                                "effective": {
                                    "type": "string",
                                    "enum": [
                                        "now",
                                        "period_end",
                                        "trial_end"
                                    ]
                                },
                                "card_required": {
                                    "type": "boolean"
                                },
                                "monthly": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "yearly": {
                                    "type": "integer",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "change_blocked": {
                        "description": "Why the plan cannot be changed here: `billed_by_agency` or `billed_by_hq` (with a `detail`).",
                        "type": "object",
                        "nullable": true
                    },
                    "cancel_available": {
                        "type": "boolean"
                    },
                    "resume_available": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "BillingQuote": {
                "description": "What a business pays on a plan for a number of locations (docs/billing.md \"Volume bands\"): the base price (first location; null for Starter, whose first band starts at 1), the graduated bands, totals in whole US dollars, the effective price per location, the next band and, for an agency client, the agency price.",
                "properties": {
                    "plan": {
                        "type": "string",
                        "enum": [
                            "starter",
                            "pro",
                            "premium"
                        ]
                    },
                    "name": {
                        "type": "string"
                    },
                    "currency": {
                        "type": "string",
                        "example": "usd"
                    },
                    "locations": {
                        "type": "integer",
                        "example": 25
                    },
                    "base": {
                        "type": "object",
                        "nullable": true
                    },
                    "bands": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "from": {
                                    "type": "integer"
                                },
                                "to": {
                                    "type": "integer"
                                },
                                "locations": {
                                    "type": "integer"
                                },
                                "unit_monthly": {
                                    "type": "integer"
                                },
                                "unit_yearly": {
                                    "type": "integer"
                                },
                                "monthly": {
                                    "type": "integer"
                                },
                                "yearly": {
                                    "type": "integer"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "monthly": {
                        "type": "integer",
                        "example": 1854
                    },
                    "yearly": {
                        "type": "integer",
                        "example": 18540
                    },
                    "effective_per_location": {
                        "type": "object"
                    },
                    "next_band": {
                        "type": "object",
                        "nullable": true
                    },
                    "agency": {
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "BillingChangeRequest": {
                "required": [
                    "plan",
                    "interval"
                ],
                "properties": {
                    "plan": {
                        "type": "string",
                        "enum": [
                            "starter",
                            "pro",
                            "premium"
                        ]
                    },
                    "interval": {
                        "type": "string",
                        "enum": [
                            "monthly",
                            "yearly"
                        ]
                    },
                    "confirm": {
                        "description": "change-plan only: true carries the change out.",
                        "type": "boolean"
                    },
                    "immediately": {
                        "description": "A downgrade starts now (prorated credit) instead of at the end of the paid period.",
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "BillingChangePreview": {
                "description": "What a plan change costs (US dollars, before tax). `estimate` is true when the amounts come from the list price for the business's locations (no subscription yet, or Stripe gave no next invoice) instead of a Stripe invoice preview.",
                "properties": {
                    "plan": {
                        "type": "string",
                        "enum": [
                            "starter",
                            "pro",
                            "premium"
                        ]
                    },
                    "plan_name": {
                        "type": "string"
                    },
                    "interval": {
                        "type": "string",
                        "enum": [
                            "monthly",
                            "yearly"
                        ]
                    },
                    "current_plan": {
                        "type": "string",
                        "nullable": true
                    },
                    "current_interval": {
                        "type": "string",
                        "nullable": true
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "start",
                            "upgrade",
                            "downgrade",
                            "switch_interval"
                        ]
                    },
                    "effective": {
                        "type": "string",
                        "enum": [
                            "now",
                            "period_end",
                            "trial_end"
                        ]
                    },
                    "effective_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "amount_due_now": {
                        "type": "number",
                        "example": 125.5
                    },
                    "credit": {
                        "type": "number",
                        "example": 0
                    },
                    "next_invoice": {
                        "properties": {
                            "date": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "amount": {
                                "type": "number",
                                "example": 399,
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "currency": {
                        "type": "string",
                        "example": "usd"
                    },
                    "estimate": {
                        "type": "boolean"
                    },
                    "card_required": {
                        "type": "boolean"
                    },
                    "card_on_file": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "BillingProblem": {
                "description": "Problem details with a `code`: 402 `plan_upgrade_required` (with `feature`, `current_plan`, `required_plan`, `required_plan_name`, `plan_required` and, on teaser routes, `teaser`), 402 `billing_locked` (with `status`, `lock_at`), 409 `billing_unconfigured`, `already_subscribed`, `no_billing_account`, `price_not_configured`, `billed_by_agency`, `billed_by_hq`, `confirmation_required` (with `preview`), `no_change`, `no_subscription`, `already_canceled`, `not_canceled`, 402 `payment_method_required` (with `checkout_url`, `pending_change`, `preview`), 402 `payment_failed`, 502 `billing_provider_error`.",
                "required": [
                    "type",
                    "title",
                    "status",
                    "code"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "example": "about:blank"
                    },
                    "title": {
                        "type": "string",
                        "example": "Payment Required"
                    },
                    "status": {
                        "type": "integer",
                        "example": 402
                    },
                    "detail": {
                        "type": "string"
                    },
                    "code": {
                        "type": "string",
                        "example": "plan_upgrade_required"
                    },
                    "feature": {
                        "type": "string",
                        "example": "source:trustpilot"
                    },
                    "current_plan": {
                        "type": "string",
                        "example": "starter"
                    },
                    "required_plan": {
                        "type": "string",
                        "example": "pro",
                        "nullable": true
                    },
                    "required_plan_name": {
                        "type": "string",
                        "example": "Pro",
                        "nullable": true
                    },
                    "plan_required": {
                        "description": "The gate for the dashboard and the MCP: `label`, the plan that includes it, `price_delta_monthly` (whole dollars a month more for this business, null when unknown) and `upgrade_url` (the billing page).",
                        "properties": {
                            "feature": {
                                "type": "string",
                                "example": "competitor_map"
                            },
                            "label": {
                                "type": "string",
                                "example": "Competitor Map"
                            },
                            "current_plan": {
                                "type": "string",
                                "example": "pro"
                            },
                            "required_plan": {
                                "type": "string",
                                "example": "premium",
                                "nullable": true
                            },
                            "required_plan_name": {
                                "type": "string",
                                "example": "Premium",
                                "nullable": true
                            },
                            "price_delta_monthly": {
                                "type": "integer",
                                "example": 250,
                                "nullable": true
                            },
                            "upgrade_url": {
                                "type": "string",
                                "format": "uri",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "teaser": {
                        "description": "Teaser routes only (Competitor Map, AI Reputation): what the current plan may see, with a `kind` and a one-line `summary`.",
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "AiSettings": {
                "required": [
                    "aiReplyMode"
                ],
                "properties": {
                    "aiReplyMode": {
                        "type": "string",
                        "example": "disabled",
                        "enum": [
                            "all",
                            "negative_only",
                            "disabled"
                        ]
                    },
                    "aiBusinessDescription": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 2000
                    },
                    "aiTone": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "professional",
                            "friendly",
                            "casual",
                            "empathetic"
                        ]
                    },
                    "aiIndustry": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    }
                },
                "type": "object"
            },
            "CompaniesResponse": {
                "type": "array",
                "items": {
                    "$ref": "#/components/schemas/Company"
                }
            },
            "CompanyAlreadyExistsResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Company Already Exists"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "CompanyEx": {
                "required": [
                    "item"
                ],
                "properties": {
                    "item": {
                        "$ref": "#/components/schemas/Company"
                    },
                    "reviewsSources": {
                        "$ref": "#/components/schemas/ReviewsSources"
                    }
                },
                "type": "object"
            },
            "CompanyInvitationNotAcceptedResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Company invitation not accepted"
                            },
                            "error": {
                                "example": "Company invitation not accepted"
                            },
                            "details": {
                                "example": "You need to accept the invitation before accessing this company. Please check your email."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "CompanyLogoNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Company Logo Not Found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "CompanyNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Company Not Found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "Company": {
                "required": [
                    "uuid",
                    "active",
                    "moderation",
                    "slug",
                    "name",
                    "phone",
                    "email",
                    "website",
                    "address",
                    "colors",
                    "logo",
                    "reviewHideInWidgetDefaultValue"
                ],
                "properties": {
                    "uuid": {
                        "$ref": "#/components/schemas/Uuid"
                    },
                    "active": {
                        "type": "boolean"
                    },
                    "moderation": {
                        "type": "string",
                        "readOnly": true,
                        "enum": [
                            "UnderModeration",
                            "Approved",
                            "Rejected"
                        ]
                    },
                    "slug": {
                        "type": "string",
                        "pattern": "^[a-z][a-z0-9-]*[a-z]$",
                        "example": "my-company",
                        "maxLength": 100,
                        "minLength": 5
                    },
                    "name": {
                        "type": "string",
                        "example": "My Company",
                        "maxLength": 250,
                        "minLength": 1
                    },
                    "locationNickname": {
                        "type": "string",
                        "example": "Northside Office",
                        "nullable": true,
                        "maxLength": 250
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "john@example.com",
                        "maxLength": 100
                    },
                    "website": {
                        "type": "string",
                        "format": "url",
                        "example": "https://www.google.com",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "address": {
                        "required": [
                            "line1",
                            "line2",
                            "country",
                            "unit",
                            "state",
                            "city"
                        ],
                        "properties": {
                            "line1": {
                                "type": "string",
                                "maxLength": 200
                            },
                            "line2": {
                                "type": "string",
                                "maxLength": 200
                            },
                            "unit": {
                                "type": "string",
                                "maxLength": 100
                            },
                            "country": {
                                "type": "string",
                                "maxLength": 100
                            },
                            "state": {
                                "type": "string",
                                "maxLength": 100
                            },
                            "city": {
                                "type": "string",
                                "maxLength": 100
                            },
                            "zip": {
                                "description": "Read-only here; set it with `PATCH /company/{company}`.",
                                "type": "string",
                                "readOnly": true,
                                "nullable": true,
                                "maxLength": 20
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "timezone": {
                        "description": "IANA zone; read-only here, set it with `PATCH /company/{company}`.",
                        "type": "string",
                        "readOnly": true,
                        "example": "America/New_York",
                        "nullable": true
                    },
                    "colors": {
                        "required": [
                            "primary",
                            "secondary",
                            "text",
                            "background"
                        ],
                        "properties": {
                            "primary": {
                                "$ref": "#/components/schemas/CssColor"
                            },
                            "secondary": {
                                "$ref": "#/components/schemas/CssColor"
                            },
                            "text": {
                                "$ref": "#/components/schemas/CssColor"
                            },
                            "background": {
                                "$ref": "#/components/schemas/CssColor"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "logo": {
                        "type": "string",
                        "readOnly": true,
                        "example": "https://www.server.com/images/real_url_to_image.jpg",
                        "nullable": true
                    },
                    "hasLogo": {
                        "description": "True when the business uploaded a logo; false when `logo` is the default image (DELETE /company/{company}/logo removes it).",
                        "type": "boolean",
                        "readOnly": true
                    },
                    "reviewHideInWidgetDefaultValue": {
                        "description": "Deprecated: always false and ignored when sent. New reviews are never hidden automatically (www/docs/widgets.md \"Hidden reviews\"); hide single reviews instead.",
                        "type": "boolean",
                        "deprecated": true
                    },
                    "sourcesOrder": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "nullable": true
                    },
                    "isHQ": {
                        "type": "boolean",
                        "writeOnly": true,
                        "nullable": true
                    },
                    "aiReplyMode": {
                        "type": "string",
                        "example": "disabled",
                        "enum": [
                            "all",
                            "negative_only",
                            "disabled"
                        ]
                    },
                    "aiBusinessDescription": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 2000
                    },
                    "aiTone": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "professional",
                            "friendly",
                            "casual",
                            "empathetic"
                        ]
                    },
                    "aiIndustry": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "aiRepliesUsedThisMonth": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 5
                    },
                    "aiRepliesLimit": {
                        "type": "integer",
                        "readOnly": true,
                        "example": 50
                    },
                    "hqCompany": {
                        "description": "The HQ this location belongs to (multi-location), or null.",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "readOnly": true,
                        "nullable": true
                    },
                    "agency": {
                        "description": "The agency this business is a client of (directly, or through its HQ; docs/agencies.md), or null.",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "slug": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "readOnly": true,
                        "nullable": true
                    },
                    "locationsCount": {
                        "description": "Locations that have this company as their HQ (0 for a location or a single company).",
                        "type": "integer",
                        "readOnly": true
                    },
                    "access": {
                        "description": "How the signed-in user reaches this company (docs/multi-location.md): `via` member | hq | agency | superadmin, `allLocations` = their own membership covers every location of this HQ, `groupAccess` = the \"All locations\" views (`/api/company/{uuid}/locations/...`) are open to them. Null when unknown.",
                        "properties": {
                            "role": {
                                "type": "string",
                                "nullable": true
                            },
                            "via": {
                                "type": "string",
                                "enum": [
                                    "member",
                                    "hq",
                                    "agency",
                                    "superadmin"
                                ]
                            },
                            "allLocations": {
                                "type": "boolean"
                            },
                            "groupAccess": {
                                "type": "boolean"
                            }
                        },
                        "type": "object",
                        "readOnly": true,
                        "nullable": true
                    },
                    "autoConnectSources": {
                        "description": "Connect review-site profiles the radar / discovery find by themselves (change it with `PATCH /api/company/{company}` `{\"auto_connect_sources\": true}`).",
                        "type": "boolean",
                        "readOnly": true
                    }
                },
                "type": "object"
            },
            "CreateCompany": {
                "required": [
                    "companyName",
                    "companySlug",
                    "email"
                ],
                "properties": {
                    "companyName": {
                        "type": "string",
                        "example": "My Company",
                        "maxLength": 250,
                        "minLength": 1
                    },
                    "locationNickname": {
                        "type": "string",
                        "example": "Northside Office",
                        "nullable": true,
                        "maxLength": 250
                    },
                    "companySlug": {
                        "type": "string",
                        "pattern": "^[a-z][a-z0-9-]*[a-z]$",
                        "example": "my-company",
                        "maxLength": 100,
                        "minLength": 5
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "john@example.com",
                        "maxLength": 100
                    },
                    "address": {
                        "properties": {
                            "line1": {
                                "type": "string",
                                "nullable": true,
                                "maxLength": 200
                            },
                            "line2": {
                                "type": "string",
                                "nullable": true,
                                "maxLength": 200
                            },
                            "unit": {
                                "type": "string",
                                "nullable": true,
                                "maxLength": 100
                            },
                            "country": {
                                "type": "string",
                                "nullable": true,
                                "maxLength": 100
                            },
                            "state": {
                                "type": "string",
                                "nullable": true,
                                "maxLength": 100
                            },
                            "city": {
                                "type": "string",
                                "nullable": true,
                                "maxLength": 100
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "isHQ": {
                        "type": "boolean"
                    },
                    "hqCompany": {
                        "description": "The HQ (uuid) the new location belongs to and is billed under; the caller must be an owner or admin there (directly, through an agency or as a platform super admin). null = a separate business (not billed under any HQ); absent = as before (under the creator's own HQ when they administer it).",
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "CompanyUser": {
                "required": [
                    "uuid",
                    "name",
                    "email",
                    "role",
                    "status"
                ],
                "properties": {
                    "uuid": {
                        "$ref": "#/components/schemas/Uuid"
                    },
                    "name": {
                        "type": "string",
                        "example": "John Doe",
                        "maxLength": 100,
                        "minLength": 1
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "readOnly": true,
                        "example": "john@example.com",
                        "maxLength": 100
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "role": {
                        "type": "string",
                        "example": "user",
                        "enum": [
                            "owner",
                            "super_admin",
                            "admin",
                            "approver",
                            "reviewer",
                            "viewer",
                            "user"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "readOnly": true,
                        "example": "active",
                        "enum": [
                            "active",
                            "pending"
                        ]
                    },
                    "allLocations": {
                        "description": "This membership of an HQ also covers all of its locations (docs/multi-location.md); change it with PATCH /api/company/{uuid}/locations/members/{user}.",
                        "type": "boolean",
                        "readOnly": true
                    }
                },
                "type": "object"
            },
            "CompanyUsersList": {
                "required": [
                    "users"
                ],
                "properties": {
                    "users": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/CompanyUser"
                        }
                    }
                },
                "type": "object"
            },
            "InsufficientPermissionsResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "You do not have permission to perform this action."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "InviteUserRequest": {
                "required": [
                    "email",
                    "name",
                    "role"
                ],
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "john@example.com",
                        "maxLength": 255
                    },
                    "name": {
                        "type": "string",
                        "example": "John Doe",
                        "maxLength": 100,
                        "minLength": 1
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "role": {
                        "type": "string",
                        "example": "user",
                        "enum": [
                            "owner",
                            "super_admin",
                            "admin",
                            "approver",
                            "reviewer",
                            "viewer",
                            "user"
                        ]
                    },
                    "allLocations": {
                        "description": "For an HQ with locations: the member also uses every location with this role (docs/multi-location.md). Default: true for admins and super admins, false for users.",
                        "type": "boolean",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "UpdateUserRequest": {
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "John Doe",
                        "nullable": true,
                        "maxLength": 100,
                        "minLength": 1
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "role": {
                        "type": "string",
                        "example": "admin",
                        "nullable": true,
                        "enum": [
                            "owner",
                            "super_admin",
                            "admin",
                            "approver",
                            "reviewer",
                            "viewer",
                            "user"
                        ]
                    }
                },
                "type": "object"
            },
            "UserAlreadyExistsInCompanyResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "User is already a member of this company."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "CompanyUserNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "User not found."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "CssColor": {
                "type": "string",
                "pattern": "^#[0-9A-Fa-f]{3,6}$",
                "example": "#F1B1C1",
                "maxLength": 7,
                "minLength": 4
            },
            "GeneralResponse": {
                "required": [
                    "message"
                ],
                "properties": {
                    "message": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "InternalServerErrorResponse": {
                "description": "This class is a description of the Laravel standard error scheme issued in case of an internal server error.",
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Server Error"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "NotImplementedResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Not Implemented."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "NotificationIconType": {
                "type": "string",
                "readOnly": true,
                "enum": [
                    "positive",
                    "negative",
                    "neutral"
                ]
            },
            "NotificationNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Notification Not Found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "Notification": {
                "required": [
                    "uuid",
                    "companyUuid",
                    "type",
                    "text",
                    "iconType",
                    "isRead",
                    "createdAt"
                ],
                "properties": {
                    "uuid": {
                        "$ref": "#/components/schemas/Uuid"
                    },
                    "companyUuid": {
                        "$ref": "#/components/schemas/Uuid"
                    },
                    "type": {
                        "$ref": "#/components/schemas/NotificationType"
                    },
                    "text": {
                        "type": "string",
                        "readOnly": true
                    },
                    "iconType": {
                        "$ref": "#/components/schemas/NotificationIconType"
                    },
                    "isRead": {
                        "type": "boolean"
                    },
                    "createdAt": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    }
                },
                "type": "object"
            },
            "NotificationSettings": {
                "properties": {
                    "web": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/NotificationType"
                        },
                        "uniqueItems": true
                    },
                    "email": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/NotificationType"
                        },
                        "uniqueItems": true
                    },
                    "push_types": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/NotificationType"
                        },
                        "uniqueItems": true
                    },
                    "weekly_digest": {
                        "description": "Weekly email digest (docs/weekly-digest.md). Default true; left out of a PUT, the stored choice is kept.",
                        "type": "boolean"
                    },
                    "celebration_post": {
                        "description": "Celebration posts by email (docs/celebrations.md): a ready-to-share post when the business earns a milestone, award or grade. Default true; left out of a PUT, the stored choice is kept.",
                        "type": "boolean"
                    },
                    "suppressed_since": {
                        "description": "Read-only. Since when the user's own email address has been on the mail suppression list (a bounce, spam complaint or unsubscribe reported by the mail provider): the app sends it no mail. Null when the address is mailed. Ignored in a PUT.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "NotificationType": {
                "type": "string",
                "readOnly": true,
                "enum": [
                    "SystemUpdated",
                    "Announcements",
                    "ReviewAdded",
                    "ReviewUpdated",
                    "ReviewAddedResponse",
                    "ReviewUpdatedResponse",
                    "ReviewRemoved",
                    "MonthlyReviewSummary",
                    "ReviewSourceAdded",
                    "ReviewSourceRemoved",
                    "ReviewSourceReconnected",
                    "ReviewSourceConnectionError",
                    "ReviewSourceConfigurationError",
                    "ReviewParseCompleted",
                    "ReviewParsePartial",
                    "ReviewParseError",
                    "AgentActionsPending",
                    "BillingAttention",
                    "ReviewMentionFound",
                    "AiPerceptionChanged",
                    "ReviewPageFeedback",
                    "SiteRadarDigest",
                    "ReviewSourceAutoConnected",
                    "AgentEscalation",
                    "AiReputationAlert",
                    "CompetitorAlert",
                    "AwardEarned",
                    "LoginNeeded",
                    "CelebrationPost",
                    "ReportsReady",
                    "FeedbackReported",
                    "RecoveryCaseOpened",
                    "PolicyChanged",
                    "SharePackageWithdrawn",
                    "ExportFailed",
                    "ImpersonationSuspect",
                    "SiteRequestUpdate"
                ]
            },
            "NotificationsResponse": {
                "required": [
                    "page",
                    "itemsPerPage",
                    "totalQuantity",
                    "unreadQuantity",
                    "items"
                ],
                "properties": {
                    "page": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "itemsPerPage": {
                        "type": "integer",
                        "format": "int32",
                        "nullable": true,
                        "minimum": 0
                    },
                    "totalQuantity": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "unreadQuantity": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Notification"
                        }
                    }
                },
                "type": "object"
            },
            "PublishableKey": {
                "required": [
                    "id",
                    "name",
                    "integration",
                    "prefix",
                    "allowed_origins",
                    "created_via",
                    "created_by_client",
                    "last_used_at",
                    "revoked_at",
                    "created_at"
                ],
                "properties": {
                    "id": {
                        "type": "integer",
                        "example": 3
                    },
                    "name": {
                        "type": "string",
                        "example": "Main website",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "integration": {
                        "description": "The integration the key was made for (the dashboard's guided \"Connect\" flow); null = made by hand, or before 2026-11.",
                        "type": "string",
                        "example": "wordpress",
                        "nullable": true,
                        "enum": [
                            "wordpress"
                        ]
                    },
                    "prefix": {
                        "type": "string",
                        "example": "gk_pub_Ab3x"
                    },
                    "allowed_origins": {
                        "description": "Websites allowed to call the public API from a browser; null = any.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "example": "https://www.example.com"
                        },
                        "nullable": true
                    },
                    "created_via": {
                        "description": "How the key was made: dashboard, mcp or api; null = before 2026-11.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "dashboard",
                            "mcp",
                            "api"
                        ]
                    },
                    "created_by_client": {
                        "description": "The AI app that made the key (its registered OAuth client name), e.g. \"Claude\".",
                        "type": "string",
                        "example": "Claude",
                        "nullable": true
                    },
                    "last_used_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "revoked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "CreatedPublishableKey": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/PublishableKey"
                    },
                    {
                        "required": [
                            "key"
                        ],
                        "properties": {
                            "key": {
                                "description": "The publishable key. Shown only in this response.",
                                "type": "string",
                                "example": "gk_pub_Ab3xR0x9yTqZ2v7mN1kP5sW8cD4fG6hJ"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1ReportPageMeta": {
                "description": "OpenAPI schema of a reports API page's `meta` (www/docs/reports.md); the query parameters are in ReportParameters.",
                "properties": {
                    "report": {
                        "type": "string"
                    },
                    "columns": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "count": {
                        "description": "Rows on this page.",
                        "type": "integer"
                    },
                    "limit": {
                        "type": "integer"
                    },
                    "next_cursor": {
                        "type": "string",
                        "nullable": true
                    },
                    "has_more": {
                        "type": "boolean"
                    },
                    "locations": {
                        "description": "Businesses in the walk.",
                        "type": "integer"
                    },
                    "start_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "end_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "interval": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "day",
                            "week",
                            "month"
                        ]
                    },
                    "skipped": {
                        "description": "Businesses left out because their plan lacks the report's feature.",
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "timezone": {
                        "type": "string",
                        "example": "UTC"
                    }
                },
                "type": "object"
            },
            "RequestTooLargeErrorResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "The POST data is too large."
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "ResourceNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "API key not found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "ImportReviews": {
                "required": [
                    "imported",
                    "line_errors"
                ],
                "properties": {
                    "imported": {
                        "type": "integer",
                        "example": 124
                    },
                    "line_errors": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "line": {
                                    "type": "integer",
                                    "example": 12
                                },
                                "errors": {
                                    "type": "array",
                                    "items": {
                                        "type": "string",
                                        "example": "Please enter your email."
                                    }
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "ReviewCountByRating": {
                "required": [
                    "total"
                ],
                "properties": {
                    "total": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "1": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "2": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "3": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "4": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "5": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    }
                },
                "type": "object"
            },
            "ReviewEx": {
                "required": [
                    "item"
                ],
                "properties": {
                    "item": {
                        "$ref": "#/components/schemas/Review"
                    },
                    "reviewsSource": {
                        "$ref": "#/components/schemas/ReviewsSource"
                    }
                },
                "type": "object"
            },
            "V1ReviewHistory": {
                "required": [
                    "review",
                    "site",
                    "site_name",
                    "removed_at",
                    "removal_reason",
                    "edited_count",
                    "summary",
                    "versions",
                    "text_policy"
                ],
                "properties": {
                    "review": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "site": {
                        "description": "The review platform slug.",
                        "type": "string",
                        "example": "google"
                    },
                    "site_name": {
                        "description": "Its display name.",
                        "type": "string",
                        "example": "Google"
                    },
                    "removed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "removal_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "edited_count": {
                        "type": "integer"
                    },
                    "summary": {
                        "type": "string"
                    },
                    "versions": {
                        "description": "Oldest first.",
                        "type": "array",
                        "items": {
                            "required": [
                                "reason",
                                "changed_at",
                                "rating",
                                "text",
                                "author",
                                "url"
                            ],
                            "properties": {
                                "reason": {
                                    "type": "string",
                                    "enum": [
                                        "edited",
                                        "removed_from_source",
                                        "restored",
                                        "deleted_by_owner",
                                        "source_removed"
                                    ]
                                },
                                "changed_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "rating": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "text": {
                                    "description": "Null when withheld (`text_policy: aggregate`).",
                                    "type": "string",
                                    "nullable": true
                                },
                                "author": {
                                    "description": "Null when withheld (`text_policy: aggregate`).",
                                    "type": "string",
                                    "nullable": true
                                },
                                "url": {
                                    "type": "string",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "text_policy": {
                        "description": "`aggregate`: a Yelp review whose text and author are withheld; `yelp_consent`: included after consent (internal use only). Null for every other review.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "aggregate",
                            "yelp_consent"
                        ]
                    }
                },
                "type": "object"
            },
            "V1YelpTextMeta": {
                "description": "Whether Yelp review text is included for this company and how to record the consent.",
                "required": [
                    "included",
                    "consent_recorded",
                    "consent_field",
                    "consent_version",
                    "warning",
                    "terms_url"
                ],
                "properties": {
                    "included": {
                        "type": "boolean"
                    },
                    "consent_recorded": {
                        "type": "boolean"
                    },
                    "consent_field": {
                        "type": "string",
                        "example": "yelp_consent"
                    },
                    "consent_version": {
                        "type": "string"
                    },
                    "warning": {
                        "type": "string"
                    },
                    "terms_url": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "ReviewLength": {
                "type": "integer",
                "format": "int32",
                "maxLength": 65000,
                "minLength": 1
            },
            "ReviewNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Review Not Found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "ReviewPost": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/Review"
                    },
                    {
                        "properties": {
                            "rating": {
                                "readOnly": false
                            },
                            "text": {
                                "readOnly": false
                            },
                            "companyResponseText": {
                                "readOnly": false
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "ReviewRating": {
                "type": "integer",
                "format": "int32",
                "maximum": 5,
                "minimum": 1
            },
            "Review": {
                "required": [
                    "uuid",
                    "username",
                    "rating",
                    "likes",
                    "dislikes",
                    "text",
                    "sourceDriver",
                    "sourceExt",
                    "tags",
                    "hideInWidget",
                    "avatar",
                    "companyLogo",
                    "publishedDate",
                    "updatedDate",
                    "wasUpdated",
                    "companyResponseText",
                    "companyResponseAt",
                    "overrideUsername",
                    "overrideAvatar",
                    "overrideTitle",
                    "overrideCompanyLogo",
                    "overrideDesignation",
                    "overrideIndustry",
                    "overrideLocation",
                    "externalUrl",
                    "createdAt",
                    "updatedAt",
                    "deletedAt"
                ],
                "properties": {
                    "uuid": {
                        "$ref": "#/components/schemas/Uuid"
                    },
                    "username": {
                        "type": "string",
                        "readOnly": true,
                        "nullable": true,
                        "maxLength": 191
                    },
                    "rating": {
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/ReviewRating"
                            },
                            {
                                "readOnly": true
                            }
                        ]
                    },
                    "likes": {
                        "type": "integer",
                        "format": "int32",
                        "readOnly": true,
                        "minimum": 0
                    },
                    "dislikes": {
                        "type": "integer",
                        "format": "int32",
                        "readOnly": true,
                        "minimum": 0
                    },
                    "text": {
                        "type": "string",
                        "readOnly": true,
                        "nullable": true,
                        "maxLength": 65000
                    },
                    "sourceDriver": {
                        "$ref": "#/components/schemas/ReviewsSourceDriver"
                    },
                    "site": {
                        "description": "The review platform (`google`, `yelp`, `direct`, `grades`, ...), the same for every collector of one platform. Use it to pick a logo.",
                        "type": "string",
                        "readOnly": true,
                        "example": "google"
                    },
                    "siteName": {
                        "description": "The name owners read for the review's site (as `site_name` of V1Review): the brand (\"Google\"), \"Reviews on Grades.com\" (`grades`), \"Added via API\" (`direct`) or \"Imported\" (a file import, `grades`).",
                        "type": "string",
                        "readOnly": true,
                        "example": "Google"
                    },
                    "replyHandling": {
                        "description": "Review lists only: how a reply gets out, the same answer as `GET .../reviews/{review}/handling` `reply`: `site` (matrix site; `api` = added through the API or imported from a file, \"Added via API\"), `siteLabel`, `channel` (api, client_login, manual), `channelLabel`, `automated`, `canPushReply` (the review's source posts replies through an API).",
                        "properties": {
                            "site": {
                                "type": "string"
                            },
                            "siteLabel": {
                                "type": "string"
                            },
                            "channel": {
                                "type": "string"
                            },
                            "channelLabel": {
                                "type": "string"
                            },
                            "automated": {
                                "type": "boolean"
                            },
                            "canPushReply": {
                                "type": "boolean"
                            }
                        },
                        "type": "object",
                        "readOnly": true
                    },
                    "sourceExt": {
                        "description": "Additional information from the link (for `direct` source only).",
                        "type": "string",
                        "readOnly": true,
                        "nullable": true,
                        "maxLength": 65000
                    },
                    "tags": {
                        "description": "Legacy tags stored on the review (read-only; tag management was removed).",
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "readOnly": true
                    },
                    "hideInWidget": {
                        "type": "boolean"
                    },
                    "avatar": {
                        "type": "string",
                        "readOnly": true,
                        "nullable": true,
                        "maxLength": 255
                    },
                    "companyLogo": {
                        "type": "string",
                        "readOnly": true,
                        "nullable": true,
                        "maxLength": 255
                    },
                    "companyResponseText": {
                        "type": "string",
                        "readOnly": true,
                        "nullable": true,
                        "maxLength": 65000
                    },
                    "companyResponseAt": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true,
                        "nullable": true
                    },
                    "overrideUsername": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 100
                    },
                    "overrideAvatar": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "overrideTitle": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "overrideCompanyLogo": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "overrideDesignation": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "overrideIndustry": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "overrideLocation": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "externalUrl": {
                        "type": "string",
                        "format": "url",
                        "readOnly": true,
                        "nullable": true
                    },
                    "publishedDate": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "updatedDate": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true,
                        "nullable": true
                    },
                    "wasUpdated": {
                        "type": "boolean",
                        "readOnly": true
                    },
                    "createdAt": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "updatedAt": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true
                    },
                    "deletedAt": {
                        "type": "string",
                        "format": "date-time",
                        "readOnly": true,
                        "nullable": true
                    },
                    "editedCount": {
                        "description": "Review lists only: how many times the author edited the review (the archive's `edited` versions, the same count as `edited_count` of `GET .../review/{review}/history`).",
                        "type": "integer",
                        "readOnly": true,
                        "minimum": 0
                    },
                    "removalReason": {
                        "description": "Why the review is no longer on its site (`removed_from_source`); null while it is live. The review stays in the archive (docs/review-lifecycle.md).",
                        "type": "string",
                        "nullable": true
                    },
                    "reviewTags": {
                        "description": "Tags on the review (www/docs/review-tags.md); the same objects as API v1 `tags`.",
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "sentiment": {
                        "description": "positive, neutral, negative or mixed (null until analyzed).",
                        "type": "string",
                        "nullable": true
                    },
                    "language": {
                        "description": "The review's language (ISO 639-1), null when unknown.",
                        "type": "string",
                        "nullable": true
                    },
                    "textEn": {
                        "description": "Machine translation of `text` into English (\"Translated by AI\"), as V1Review `text_en`.",
                        "type": "string",
                        "nullable": true
                    },
                    "translation": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1Translation"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "grades": {
                        "description": "Reviews left on Grades.com (`sourceDriver` direct): channel `mode` (public, curated, private), `status`, `featured`, `shown`, `counts`, `media` (photos and video) and `history`; null for any other review.",
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ReviewsOrderByItem": {
                "required": [
                    "field",
                    "direction"
                ],
                "properties": {
                    "field": {
                        "type": "string",
                        "enum": [
                            "username",
                            "publishedDate",
                            "rating",
                            "hasCompanyResponse"
                        ]
                    },
                    "direction": {
                        "type": "string",
                        "enum": [
                            "asc",
                            "desc"
                        ]
                    }
                },
                "type": "object"
            },
            "ReviewsResponse": {
                "required": [
                    "page",
                    "itemsPerPage",
                    "orderBy",
                    "items"
                ],
                "properties": {
                    "page": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    },
                    "itemsPerPage": {
                        "type": "integer",
                        "format": "int32",
                        "nullable": true,
                        "minimum": 0
                    },
                    "startDate": {
                        "type": "string",
                        "format": "date",
                        "readOnly": true
                    },
                    "endDate": {
                        "type": "string",
                        "format": "date",
                        "readOnly": true
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "text",
                            "image",
                            "rating"
                        ]
                    },
                    "minRating": {
                        "$ref": "#/components/schemas/ReviewRating"
                    },
                    "maxRating": {
                        "$ref": "#/components/schemas/ReviewRating"
                    },
                    "hasCompanyResponse": {
                        "type": "boolean"
                    },
                    "minLength": {
                        "$ref": "#/components/schemas/ReviewLength"
                    },
                    "maxLength": {
                        "$ref": "#/components/schemas/ReviewLength"
                    },
                    "hideInWidget": {
                        "type": "boolean"
                    },
                    "s": {
                        "type": "string"
                    },
                    "orderBy": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/ReviewsOrderByItem"
                        }
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Review"
                        }
                    },
                    "totalQuantity": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                    }
                },
                "type": "object"
            },
            "ReviewsStatsByDaysResponse": {
                "additionalProperties": {
                    "properties": {
                        "direct": {
                            "$ref": "#/components/schemas/ReviewCountByRating"
                        },
                        "google": {
                            "$ref": "#/components/schemas/ReviewCountByRating"
                        },
                        "facebook": {
                            "$ref": "#/components/schemas/ReviewCountByRating"
                        }
                    },
                    "type": "object",
                    "additionalProperties": {
                        "$ref": "#/components/schemas/ReviewCountByRating"
                    }
                }
            },
            "ReviewsStatsResponse": {
                "properties": {
                    "direct": {
                        "$ref": "#/components/schemas/ReviewCountByRating"
                    },
                    "google": {
                        "$ref": "#/components/schemas/ReviewCountByRating"
                    },
                    "facebook": {
                        "$ref": "#/components/schemas/ReviewCountByRating"
                    }
                },
                "type": "object",
                "additionalProperties": {
                    "$ref": "#/components/schemas/ReviewCountByRating"
                }
            },
            "V1ReviewPageActivity": {
                "description": "OpenAPI schema of a review page's activity (`GET .../review-pages/{page}/activity`, docs/review-pages.md \"Activity\",\n{@see \\App\\Services\\ReviewPages\\PageActivity}). Labels name devices or places, never people; nothing is ranked.",
                "required": [
                    "page_id",
                    "from",
                    "to",
                    "days",
                    "visits",
                    "clicked",
                    "click_rate",
                    "clicks",
                    "clicks_by_site",
                    "by_source",
                    "by_label",
                    "reviews"
                ],
                "properties": {
                    "page_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "from": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-10-14"
                    },
                    "to": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-11-12"
                    },
                    "days": {
                        "type": "integer",
                        "example": 30
                    },
                    "visits": {
                        "description": "Visitors of the page, one per visitor and day.",
                        "type": "integer",
                        "example": 40
                    },
                    "clicked": {
                        "description": "Of them, visitors who clicked at least one review-site button or \"Leave a review on Grades.com\".",
                        "type": "integer",
                        "example": 18
                    },
                    "click_rate": {
                        "description": "clicked / visits (0-1); null without visits.",
                        "type": "number",
                        "example": 0.45,
                        "nullable": true
                    },
                    "clicks": {
                        "description": "Button clicks (one per visitor, button and day).",
                        "type": "integer",
                        "example": 21
                    },
                    "redirects": {
                        "description": "Visits the page sent straight to its destination site (one per visitor and day; also counted in clicks and clicks_by_site). Whether a review followed is not known.",
                        "type": "integer",
                        "example": 0
                    },
                    "redirects_note": {
                        "description": "The line to show next to it.",
                        "type": "string"
                    },
                    "clicks_by_site": {
                        "description": "Per button, alphabetically by name. `link_id` `direct` = \"Leave a review on Grades.com\".",
                        "type": "array",
                        "items": {
                            "properties": {
                                "link_id": {
                                    "type": "string"
                                },
                                "site": {
                                    "description": "Driver of the site; `grades` for the Grades.com form; null for a custom link.",
                                    "type": "string",
                                    "nullable": true
                                },
                                "name": {
                                    "type": "string",
                                    "example": "Google"
                                },
                                "clicks": {
                                    "type": "integer"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "by_source": {
                        "description": "Every source in a fixed order: link, qr (printed QR code), counter (counter screen), app-qr, app-tap (Grades.com Android app), request (review request).",
                        "type": "array",
                        "items": {
                            "properties": {
                                "source": {
                                    "type": "string",
                                    "enum": [
                                        "link",
                                        "qr",
                                        "counter",
                                        "app-qr",
                                        "app-tap",
                                        "request"
                                    ]
                                },
                                "name": {
                                    "type": "string",
                                    "example": "Counter screen"
                                },
                                "visits": {
                                    "type": "integer"
                                },
                                "clicked": {
                                    "type": "integer"
                                },
                                "click_rate": {
                                    "type": "number",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "by_label": {
                        "description": "Per label (the device or place from `?label=`), alphabetically; null = no label, listed last. Only labels with activity in the period.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "label": {
                                    "type": "string",
                                    "example": "Front desk",
                                    "nullable": true
                                },
                                "visits": {
                                    "type": "integer"
                                },
                                "clicked": {
                                    "type": "integer"
                                },
                                "click_rate": {
                                    "type": "number",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "reviews": {
                        "description": "New reviews of the business published in the period, all sites. Not tied to visits.",
                        "properties": {
                            "new": {
                                "type": "integer",
                                "example": 3
                            },
                            "by_site": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "site": {
                                            "type": "string",
                                            "example": "google"
                                        },
                                        "name": {
                                            "type": "string",
                                            "example": "Google"
                                        },
                                        "count": {
                                            "type": "integer"
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "note": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewPostCandidate": {
                "description": "OpenAPI schema of a review a set of posts can be made from ({@see \\App\\Services\\ReviewPosts\\ReviewPostCandidates::item()}).",
                "required": [
                    "review_id",
                    "site",
                    "rating",
                    "date",
                    "reviewer",
                    "text",
                    "units",
                    "suggested",
                    "eligible",
                    "ineligible_reason"
                ],
                "properties": {
                    "review_id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "site": {
                        "properties": {
                            "driver": {
                                "description": "The platform slug.",
                                "type": "string",
                                "example": "google"
                            },
                            "label": {
                                "description": "Plain text as the posts show it.",
                                "type": "string",
                                "example": "Google review"
                            }
                        },
                        "type": "object"
                    },
                    "rating": {
                        "type": "integer",
                        "nullable": true
                    },
                    "date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "reviewer": {
                        "description": "First name and last initial.",
                        "type": "string",
                        "example": "Dana R."
                    },
                    "text": {
                        "description": "The review text (clinical terms scrubbed for healthcare businesses).",
                        "type": "string"
                    },
                    "units": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "i": {
                                    "type": "integer"
                                },
                                "text": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "default_keep": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        },
                        "nullable": true
                    },
                    "default_short_keep": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        },
                        "nullable": true
                    },
                    "suggested": {
                        "type": "boolean"
                    },
                    "eligible": {
                        "type": "boolean"
                    },
                    "ineligible_reason": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "low_rating",
                            "clinical",
                            "too_short",
                            "too_long",
                            "unknown_source",
                            "no_text",
                            "removed",
                            "not_public",
                            "yelp"
                        ]
                    }
                },
                "type": "object"
            },
            "V1ReviewPostInput": {
                "required": [
                    "review_id"
                ],
                "properties": {
                    "review_id": {
                        "description": "The review uuid (or numeric id).",
                        "type": "string"
                    },
                    "keep": {
                        "description": "Unit indexes to keep (cuts only; an ellipsis marks every gap). Default: the whole review when it fits, else its strongest sentence.",
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "short_keep": {
                        "description": "Unit indexes of the quote for the small sizes (at most 70 characters). Default: the strongest sentence of the kept ones.",
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "theme": {
                        "type": "string",
                        "default": "dark",
                        "enum": [
                            "dark",
                            "light"
                        ]
                    },
                    "cta_label": {
                        "type": "string",
                        "example": "Book a visit",
                        "maxLength": 24
                    },
                    "url_text": {
                        "description": "Shown as text only.",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 60
                    },
                    "logo": {
                        "type": "string",
                        "enum": [
                            "brand",
                            "initials"
                        ]
                    },
                    "colors": {
                        "properties": {
                            "primary": {
                                "type": "string",
                                "pattern": "^#[0-9a-fA-F]{6}$"
                            },
                            "secondary": {
                                "type": "string",
                                "pattern": "^#[0-9a-fA-F]{6}$"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewPostPreview": {
                "description": "OpenAPI schema of a Social Posts preview: full HTML documents (fonts and logos inlined, no network).",
                "required": [
                    "sizes",
                    "video",
                    "quote",
                    "caption",
                    "rating"
                ],
                "properties": {
                    "sizes": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "key": {
                                    "type": "string",
                                    "example": "300x250"
                                },
                                "group": {
                                    "description": "`social` (1080x1080, 1200x628) or `google_ads` (the 10 display sizes).",
                                    "type": "string",
                                    "enum": [
                                        "social",
                                        "google_ads"
                                    ]
                                },
                                "width": {
                                    "type": "integer"
                                },
                                "height": {
                                    "type": "integer"
                                },
                                "html": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "video": {
                        "properties": {
                            "width": {
                                "type": "integer",
                                "example": 1080
                            },
                            "height": {
                                "type": "integer",
                                "example": 1920
                            },
                            "duration_ms": {
                                "type": "integer",
                                "example": 12480
                            },
                            "html": {
                                "description": "Loops on its own clock.",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "quote": {
                        "properties": {
                            "main": {
                                "type": "string"
                            },
                            "short": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "keep": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "short_keep": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "caption": {
                        "type": "string"
                    },
                    "rating": {
                        "properties": {
                            "value": {
                                "type": "number"
                            },
                            "count": {
                                "type": "integer"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewPostSet": {
                "description": "OpenAPI schema of a set of Social Posts (www/docs/review-posts.md \"API\"; {@see \\App\\Services\\ReviewPosts\\ReviewPostSets::payload()}).",
                "required": [
                    "id",
                    "status",
                    "review_id",
                    "quote",
                    "style",
                    "rating",
                    "files",
                    "error",
                    "created_by",
                    "created_at",
                    "rendered_at"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "queued",
                            "rendering",
                            "ready",
                            "failed"
                        ]
                    },
                    "review_id": {
                        "description": "The review uuid.",
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "quote": {
                        "properties": {
                            "main": {
                                "type": "string"
                            },
                            "short": {
                                "description": "The quote of the small sizes.",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "style": {
                        "properties": {
                            "theme": {
                                "type": "string",
                                "enum": [
                                    "dark",
                                    "light"
                                ]
                            },
                            "cta_label": {
                                "type": "string",
                                "example": "Book a visit"
                            },
                            "url_text": {
                                "type": "string",
                                "example": "baysideautocare.com",
                                "nullable": true
                            },
                            "logo": {
                                "type": "string",
                                "enum": [
                                    "brand",
                                    "initials"
                                ]
                            },
                            "colors": {
                                "properties": {
                                    "primary": {
                                        "type": "string",
                                        "example": "#6B42FE",
                                        "nullable": true
                                    },
                                    "secondary": {
                                        "type": "string",
                                        "example": "#00F7EF",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            }
                        },
                        "type": "object"
                    },
                    "rating": {
                        "description": "The business Grades.com profile figures shown on the posts; null when it has none (the line is left out).",
                        "properties": {
                            "value": {
                                "type": "number",
                                "example": 4.8
                            },
                            "count": {
                                "type": "integer",
                                "example": 212
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "files": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "example": "banner-300x250.png"
                                },
                                "kind": {
                                    "type": "string",
                                    "enum": [
                                        "banner",
                                        "video",
                                        "poster",
                                        "caption"
                                    ]
                                },
                                "group": {
                                    "description": "`social` (1080x1080, 1200x628, the video, its poster, the caption; ZIP folder `social/`) or `google_ads` (the 10 display banners; ZIP folder `google-ads/`).",
                                    "type": "string",
                                    "enum": [
                                        "social",
                                        "google_ads"
                                    ]
                                },
                                "width": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "height": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "bytes": {
                                    "type": "integer"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "error": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_by": {
                        "properties": {
                            "id": {
                                "description": "The user uuid.",
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "rendered_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ReviewReplyDelete": {
                "required": [
                    "reply",
                    "lastSyncAttempt"
                ],
                "properties": {
                    "reply": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/ReviewReply"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "lastSyncAttempt": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/ReviewReplySyncAttempt"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "ReviewReplyRequest": {
                "properties": {
                    "text": {
                        "type": "string",
                        "nullable": false,
                        "maxLength": 65000
                    }
                },
                "type": "object"
            },
            "ReviewReply": {
                "properties": {
                    "uuid": {
                        "type": "string",
                        "nullable": true
                    },
                    "text": {
                        "type": "string"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "deleted_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ReviewReplyShow": {
                "required": [
                    "reply",
                    "lastSyncAttempt"
                ],
                "properties": {
                    "reply": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/ReviewReply"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "lastSyncAttempt": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/ReviewReplySyncAttempt"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "ReviewReplySyncAttempt": {
                "properties": {
                    "operation": {
                        "type": "string",
                        "enum": [
                            "delete",
                            "upsert"
                        ]
                    },
                    "status": {
                        "type": "string"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "ReviewReplyUpsert": {
                "required": [
                    "reply",
                    "lastSyncAttempt"
                ],
                "properties": {
                    "reply": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/ReviewReply"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "lastSyncAttempt": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/ReviewReplySyncAttempt"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    }
                },
                "type": "object"
            },
            "AuthReviewSource": {
                "required": [
                    "redirect_url",
                    "driver"
                ],
                "properties": {
                    "redirect_url": {
                        "type": "string",
                        "format": "url",
                        "readOnly": true
                    },
                    "driver": {
                        "type": "string",
                        "enum": [
                            "google",
                            "facebook"
                        ]
                    }
                },
                "type": "object"
            },
            "ReviewsSourceConfig": {
                "required": [
                    "config"
                ],
                "properties": {
                    "config": {
                        "description": "Parameters for the import reviews component.",
                        "type": "object",
                        "example": {
                            "key1": "value 1",
                            "key2": "value 2",
                            "key3": "value 3"
                        },
                        "nullable": true,
                        "additionalProperties": true
                    }
                },
                "type": "object"
            },
            "ReviewsSourceDriver": {
                "description": "A review platform (google, yelp, facebook, bbb, direct, grades) or a source driver (yelp_apify, google_maps, api); as a filter a review matches when its platform or its driver is named",
                "type": "string",
                "readOnly": true,
                "example": "google"
            },
            "ReviewsSourceNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Reviews Source Not Found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "ReviewsSource": {
                "required": [
                    "active",
                    "params"
                ],
                "properties": {
                    "driver": {
                        "description": "Source driver identifier",
                        "type": "string",
                        "example": "google"
                    },
                    "active": {
                        "type": "boolean"
                    },
                    "display_name": {
                        "description": "Human-readable source name",
                        "type": "string",
                        "example": "Google"
                    },
                    "site": {
                        "description": "The review platform of the source (`google`, `yelp`, `direct`, `grades`, ...). Use it to pick a logo.",
                        "type": "string",
                        "example": "google"
                    },
                    "found_by": {
                        "description": "The review radar or source discovery found this source (dashboard badge \"Found by radar\"), or `ai_answer`: an AI answer about the business cites it (badge \"Cited by AI\").",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "radar",
                            "discovery",
                            "ai_answer"
                        ]
                    },
                    "auto_connected_at": {
                        "description": "When Grades connected it by itself (auto-connect).",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "params": {
                        "description": "Parameters for the import reviews component.",
                        "type": "object",
                        "example": {
                            "token": "XXXXX",
                            "link": "https://example.com"
                        },
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "meta": {
                        "description": "Sync health of the source. `need_reconnect` is only present once the source was flagged; `parse_state`, `apify` and `refresh_cadence` are left out when the source is embedded in a review.",
                        "properties": {
                            "need_reconnect": {
                                "description": "The authorization expired; the owner must reconnect the source.",
                                "type": "boolean"
                            },
                            "parse_state": {
                                "description": "The last review fetch. Same status values as `parse.status` of API v1.",
                                "properties": {
                                    "status": {
                                        "description": "`never`: not fetched yet; `in_progress`: the current fetch has not completed (running, or interrupted and resumed on the next run); `finished`: the last fetch completed.",
                                        "type": "string",
                                        "enum": [
                                            "never",
                                            "in_progress",
                                            "finished"
                                        ]
                                    },
                                    "last_started_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "last_finished_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "last_success_at": {
                                        "description": "When the last sync completed; kept while later runs fail (data as of).",
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "expected_count": {
                                        "description": "Reviews the site reports (null when it does not say).",
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "collected_count": {
                                        "description": "Reviews collected by the current or last fetch.",
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "error": {
                                        "description": "Why the source is not syncing, derived from its flags (parsers do not keep exception text): `reconnect_required`, `listing_not_found` (the listing is gone from the review site; collection waits for a new URL or a reconnect), `apify_failing` (3 failed runs in a row) or `apify_stale` (the scraper returned nothing for a profile with reviews). Null when healthy.",
                                        "type": "string",
                                        "nullable": true,
                                        "enum": [
                                            "reconnect_required",
                                            "listing_not_found",
                                            "apify_failing",
                                            "apify_stale"
                                        ]
                                    },
                                    "error_message": {
                                        "description": "A sentence for the owner when the error needs them (`listing_not_found`: \"This listing no longer exists on Yellow Pages. Reconnect it with the current URL or remove the source.\"); null otherwise.",
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            },
                            "apify": {
                                "description": "Health of the Apify scraper behind the source; null for drivers that are not scraped through Apify.",
                                "properties": {
                                    "failing": {
                                        "type": "boolean"
                                    },
                                    "stale_since": {
                                        "description": "Since when the scraper returns nothing for a profile that has reviews.",
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "listing_not_found_at": {
                                        "description": "When the listing was found gone from the review site (null when it was not, or the source has a new URL since).",
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "last_run_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    },
                                    "last_cost_usd": {
                                        "description": "Cost of the last run (an estimate for run-sync calls).",
                                        "type": "number",
                                        "format": "float",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            },
                            "refresh_cadence": {
                                "description": "How often new reviews are fetched: `daily` for Apify-backed drivers (`weekly` for the ones parsed once a week, e.g. zocdoc), else `minutely`.",
                                "type": "string",
                                "enum": [
                                    "minutely",
                                    "daily",
                                    "weekly"
                                ]
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "ReviewsSources": {
                "type": "array",
                "items": {
                    "$ref": "#/components/schemas/ReviewsSource"
                }
            },
            "SuccessfullyResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Successfully"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "SendResetPasswordLinkRequestBody": {
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "john@example.com",
                        "maxLength": 100
                    }
                },
                "type": "object"
            },
            "TokenExpiredResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Reset token has expired"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "TokenNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "Reset token not found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "UpdatePassword": {
                "required": [
                    "token",
                    "password"
                ],
                "properties": {
                    "token": {
                        "type": "string",
                        "maxLength": 60,
                        "minLength": 60
                    },
                    "password": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 8
                    }
                },
                "type": "object"
            },
            "UserAlreadyExistsResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "User Already Exists"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "UserLogin": {
                "required": [
                    "email",
                    "password"
                ],
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "john@example.com",
                        "maxLength": 100
                    },
                    "password": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 6
                    },
                    "remember": {
                        "type": "boolean",
                        "nullable": true,
                        "default": false
                    }
                },
                "type": "object"
            },
            "UserNotFoundResponse": {
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "User Not Found"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "UserRegister": {
                "required": [
                    "name",
                    "email",
                    "companyName",
                    "password",
                    "passwordConfirmation"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "John Doe",
                        "maxLength": 100,
                        "minLength": 3
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "john@example.com",
                        "maxLength": 100
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "companyName": {
                        "type": "string",
                        "example": "My Company",
                        "maxLength": 250
                    },
                    "companySlug": {
                        "description": "Optional short name (the company slug). Left out, it is generated from the business name.",
                        "type": "string",
                        "pattern": "^[a-z][a-z0-9-]*[a-z]$",
                        "example": "my-company",
                        "nullable": true,
                        "maxLength": 100,
                        "minLength": 5
                    },
                    "website": {
                        "description": "Optional.",
                        "type": "string",
                        "example": "https://example.com",
                        "nullable": true,
                        "maxLength": 255
                    },
                    "reviewHideInWidgetDefaultValue": {
                        "type": "boolean"
                    },
                    "password": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 8
                    },
                    "passwordConfirmation": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 8
                    }
                },
                "type": "object"
            },
            "User": {
                "required": [
                    "uuid",
                    "name",
                    "phone",
                    "email",
                    "selectedCompany",
                    "hqCompany",
                    "role"
                ],
                "properties": {
                    "uuid": {
                        "$ref": "#/components/schemas/Uuid"
                    },
                    "name": {
                        "type": "string",
                        "example": "John Doe",
                        "maxLength": 100,
                        "minLength": 3
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "readOnly": true,
                        "example": "john@example.com",
                        "maxLength": 100
                    },
                    "selectedCompany": {
                        "$ref": "#/components/schemas/Uuid"
                    },
                    "hqCompany": {
                        "type": "string",
                        "format": "uuid",
                        "readOnly": true,
                        "nullable": true
                    },
                    "role": {
                        "type": "string",
                        "example": "owner"
                    },
                    "abilities": {
                        "description": "What the role allows in the selected company (www/docs/roles.md section 2).",
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "readOnly": true
                    },
                    "isSuperadmin": {
                        "description": "Platform super admin: reaches every company with the role `super_admin` and may select any company that is not offboarded (docs/api-v1.md, Super admin).",
                        "type": "boolean",
                        "readOnly": true
                    },
                    "authProviders": {
                        "description": "How the user signs in: `password`, `google` and/or `microsoft` (docs/auth.md, docs/auth-microsoft.md).",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "password",
                                "google",
                                "microsoft"
                            ]
                        },
                        "readOnly": true
                    },
                    "googleEmail": {
                        "description": "The Google account linked for sign-in, or null.",
                        "type": "string",
                        "readOnly": true,
                        "nullable": true
                    },
                    "microsoftEmail": {
                        "description": "The address of the Microsoft account linked for sign-in (as Microsoft reported it when linked), or null.",
                        "type": "string",
                        "readOnly": true,
                        "nullable": true
                    },
                    "emailVerification": {
                        "description": "Only while sign-up e-mail verification is on (docs/auth.md section 7): `required` = the address is not verified yet and some actions are refused (403 `email_verification_required`); `lastSentAt` = the last link mailed; `undeliverableSince` = the date mail to the address started bouncing (YYYY-MM-DD).",
                        "properties": {
                            "required": {
                                "type": "boolean"
                            },
                            "lastSentAt": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "undeliverableSince": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "readOnly": true
                    },
                    "notificationTotalQuantity": {
                        "type": "integer",
                        "format": "int32",
                        "readOnly": true,
                        "minimum": 0
                    },
                    "notificationUnreadQuantity": {
                        "type": "integer",
                        "format": "int32",
                        "readOnly": true,
                        "minimum": 0
                    }
                },
                "type": "object"
            },
            "UserUpdate": {
                "required": [
                    "name",
                    "phone"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "John Doe",
                        "maxLength": 100,
                        "minLength": 3
                    },
                    "phone": {
                        "type": "string",
                        "example": "+1-201-810-0000",
                        "nullable": true,
                        "maxLength": 32,
                        "minLength": 5
                    }
                },
                "type": "object"
            },
            "Uuid": {
                "type": "string",
                "format": "uuid",
                "readOnly": true
            },
            "ValidateErrorResponse": {
                "required": [
                    "errors"
                ],
                "type": "object",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/GeneralResponse"
                    },
                    {
                        "properties": {
                            "message": {
                                "example": "One or more values are not valid: The name field is required."
                            },
                            "errors": {
                                "type": "object",
                                "additionalProperties": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    },
                                    "minItems": 1
                                }
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1DirectoryMeta": {
                "description": "Meta of every directory response.",
                "properties": {
                    "source": {
                        "type": "string",
                        "example": "grades.com"
                    },
                    "directory_url": {
                        "type": "string",
                        "format": "url"
                    },
                    "staging": {
                        "type": "boolean"
                    },
                    "disclosure": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1DirectoryCategory": {
                "properties": {
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1DirectoryPlacement": {
                "description": "A current best-of placement.",
                "properties": {
                    "landing_key": {
                        "type": "string"
                    },
                    "label": {
                        "type": "string"
                    },
                    "rank": {
                        "type": "integer"
                    },
                    "url": {
                        "type": "string",
                        "format": "url"
                    }
                },
                "type": "object"
            },
            "V1DirectoryScore": {
                "description": "The latest stored Grades.com Score of a listing, as the score version that wrote it stored it.",
                "properties": {
                    "score": {
                        "type": "number"
                    },
                    "shown": {
                        "description": "The score as pages show it (rounded).",
                        "type": "integer"
                    },
                    "grade": {
                        "type": "string",
                        "example": "A",
                        "nullable": true
                    },
                    "state": {
                        "type": "string",
                        "enum": [
                            "provisional",
                            "limited",
                            "final"
                        ]
                    },
                    "version": {
                        "type": "integer"
                    },
                    "as_of": {
                        "type": "string",
                        "format": "date"
                    },
                    "ranking_score": {
                        "type": "number"
                    },
                    "graded_reviews": {
                        "type": "integer"
                    },
                    "badge_eligible": {
                        "type": "boolean"
                    },
                    "parts": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "key": {
                                    "type": "string",
                                    "enum": [
                                        "reputation",
                                        "presence",
                                        "ai",
                                        "completeness"
                                    ]
                                },
                                "name": {
                                    "type": "string"
                                },
                                "points": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "max": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "missing": {
                                    "type": "boolean"
                                },
                                "items": {
                                    "type": "array",
                                    "items": {
                                        "properties": {
                                            "key": {
                                                "type": "string"
                                            },
                                            "label": {
                                                "type": "string"
                                            },
                                            "points": {
                                                "type": "number",
                                                "nullable": true
                                            },
                                            "max": {
                                                "type": "number",
                                                "nullable": true
                                            },
                                            "details": {
                                                "description": "The stored keys of the item but its points and max (scalars and lists of strings).",
                                                "type": "object",
                                                "additionalProperties": true
                                            }
                                        },
                                        "type": "object"
                                    }
                                }
                            },
                            "type": "object"
                        }
                    },
                    "sources": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "site": {
                                    "type": "string"
                                },
                                "reviews": {
                                    "type": "integer"
                                },
                                "rating": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "last_12_months": {
                                    "type": "integer"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1DirectoryImprove": {
                "description": "What would raise the score: items with headroom (biggest possible gain first), the points each better grade needs, the local best-of entry requirements and extras that do not move the score.",
                "properties": {
                    "version": {
                        "type": "integer"
                    },
                    "score": {
                        "type": "number"
                    },
                    "shown": {
                        "type": "integer"
                    },
                    "grade": {
                        "type": "string",
                        "nullable": true
                    },
                    "full_max": {
                        "type": "number"
                    },
                    "next_grade": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1DirectoryGradeTarget"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "targets": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1DirectoryGradeTarget"
                        }
                    },
                    "grade_requires_reviews": {
                        "description": "Null once the listing has a grade.",
                        "properties": {
                            "min": {
                                "type": "integer"
                            },
                            "have": {
                                "type": "integer"
                            },
                            "needs": {
                                "type": "integer"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "key": {
                                    "description": "<part>.<item>",
                                    "type": "string"
                                },
                                "part": {
                                    "type": "string"
                                },
                                "part_name": {
                                    "type": "string"
                                },
                                "item": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "points": {
                                    "type": "number"
                                },
                                "max": {
                                    "type": "number"
                                },
                                "headroom": {
                                    "type": "number"
                                },
                                "max_score_gain": {
                                    "type": "number"
                                },
                                "how": {
                                    "type": "string"
                                },
                                "owner_can_edit": {
                                    "type": "boolean"
                                },
                                "owner_edit_field": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "owner_edit_kind": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                        "upload",
                                        "field"
                                    ]
                                },
                                "advice": {
                                    "type": "string"
                                },
                                "details": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "not_counted": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "provisional": {
                        "properties": {
                            "reason": {
                                "type": "string",
                                "enum": [
                                    "no_ai_probe"
                                ]
                            },
                            "advice": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "best_of": {
                        "properties": {
                            "family": {
                                "type": "string"
                            },
                            "eligible": {
                                "type": "boolean"
                            },
                            "missing": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "gate_missing": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "rules": {
                                "properties": {
                                    "min_reviews": {
                                        "type": "integer"
                                    },
                                    "min_sites": {
                                        "type": "integer"
                                    },
                                    "min_last_12_months": {
                                        "type": "integer"
                                    }
                                },
                                "type": "object"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "extras": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "how": {
                                    "type": "string"
                                },
                                "owner_can_edit": {
                                    "type": "boolean"
                                },
                                "url": {
                                    "type": "string",
                                    "format": "url"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1DirectoryGradeTarget": {
                "properties": {
                    "grade": {
                        "type": "string"
                    },
                    "min_score": {
                        "type": "number"
                    },
                    "needs_points": {
                        "type": "number"
                    },
                    "reachable": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1DirectoryListing": {
                "description": "A directory listing as its public profile shows it (`GET /v1/directory/listings/{id}`).",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "example": "active"
                    },
                    "online_only": {
                        "type": "boolean"
                    },
                    "published": {
                        "type": "boolean"
                    },
                    "profile_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "category": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1DirectoryCategory"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "categories": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1DirectoryCategory"
                        }
                    },
                    "address": {
                        "description": "`line1` and `zip` are null for a service-area business.",
                        "properties": {
                            "line1": {
                                "type": "string",
                                "nullable": true
                            },
                            "city": {
                                "type": "string",
                                "nullable": true
                            },
                            "state": {
                                "type": "string",
                                "nullable": true
                            },
                            "zip": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "phone": {
                        "description": "As the profile prints it.",
                        "type": "string",
                        "nullable": true
                    },
                    "website": {
                        "type": "string",
                        "nullable": true
                    },
                    "brand": {
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "name": {
                                "type": "string"
                            },
                            "profile_url": {
                                "type": "string",
                                "format": "url"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "reviews": {
                        "properties": {
                            "total": {
                                "type": "integer"
                            },
                            "rating": {
                                "type": "number",
                                "nullable": true
                            },
                            "sites": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "site": {
                                            "type": "string"
                                        },
                                        "reviews": {
                                            "type": "integer"
                                        },
                                        "rating": {
                                            "type": "number",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "score": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1DirectoryScore"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "improve": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1DirectoryImprove"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "rankings": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1DirectoryPlacement"
                        }
                    },
                    "badge": {
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "svg_url": {
                                "type": "string",
                                "format": "url"
                            }
                        },
                        "type": "object"
                    },
                    "attributes": {
                        "description": "Attribute scores, \"Known for\" and the competitor-set comparison (docs/directory.md \"Attribute badges\"); null for a permanently closed listing read by anyone but its team.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "compared_with": {
                        "description": "\"Compared with nearby <category>\" (`leads`; `trails` for its own team only); null when there is nothing to compare or the listing is permanently closed.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "badges": {
                        "description": "The current season's attribute badges (`season`, `season_name`, `current`, `history`) plus `milestone`, `praised`, `above_beyond` and `embeds`; null for a permanently closed listing read by anyone but its team.",
                        "properties": {
                            "season": {
                                "type": "string",
                                "example": "2026-fall"
                            },
                            "season_name": {
                                "type": "string"
                            },
                            "current": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "history": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "milestone": {
                                "type": "object",
                                "nullable": true,
                                "additionalProperties": true
                            },
                            "praised": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "above_beyond": {
                                "type": "object",
                                "nullable": true,
                                "additionalProperties": true
                            },
                            "embeds": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "claim": {
                        "properties": {
                            "url": {
                                "type": "string",
                                "format": "url"
                            },
                            "claimable": {
                                "type": "boolean"
                            },
                            "can_edit": {
                                "type": "boolean"
                            },
                            "state": {
                                "description": "Only for super admins and the listing's own team.",
                                "type": "string",
                                "enum": [
                                    "unclaimed",
                                    "claimed",
                                    "managed"
                                ]
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1DirectorySearchResult": {
                "description": "A search card. `claimed` is true for a claimed and a managed listing alike; `your_company` only names a company the caller already reaches; `address`/`address_line2` are null for a service-area business.",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string",
                        "nullable": true
                    },
                    "state": {
                        "type": "string",
                        "nullable": true
                    },
                    "category": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1DirectoryCategory"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "profile_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "grade": {
                        "type": "string",
                        "nullable": true
                    },
                    "shown": {
                        "type": "integer",
                        "nullable": true
                    },
                    "score_state": {
                        "type": "string",
                        "nullable": true
                    },
                    "rating": {
                        "type": "number",
                        "nullable": true
                    },
                    "reviews": {
                        "type": "integer"
                    },
                    "address": {
                        "type": "string",
                        "nullable": true
                    },
                    "address_line2": {
                        "type": "string",
                        "nullable": true
                    },
                    "zip": {
                        "type": "string",
                        "nullable": true
                    },
                    "country": {
                        "type": "string",
                        "nullable": true
                    },
                    "phone": {
                        "description": "E.164.",
                        "type": "string",
                        "nullable": true
                    },
                    "website": {
                        "type": "string",
                        "nullable": true
                    },
                    "claimed": {
                        "type": "boolean"
                    },
                    "your_company": {
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1DirectoryRanking": {
                "description": "The ranking of a category in a place: the published best-of snapshot (`published: true`) or the as-of-today order (`preview: true`; `month`, `published_at`, `next_update_at` null).",
                "properties": {
                    "landing_key": {
                        "type": "string"
                    },
                    "title": {
                        "type": "string"
                    },
                    "category": {
                        "$ref": "#/components/schemas/V1DirectoryCategory"
                    },
                    "place": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string",
                        "format": "url"
                    },
                    "published": {
                        "type": "boolean"
                    },
                    "preview": {
                        "type": "boolean"
                    },
                    "month": {
                        "type": "string",
                        "example": "2026-10",
                        "nullable": true
                    },
                    "data_as_of": {
                        "type": "string",
                        "format": "date"
                    },
                    "published_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "next_update_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "counts": {
                        "properties": {
                            "listed": {
                                "type": "integer"
                            },
                            "eligible": {
                                "type": "integer"
                            },
                            "brands": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "bar": {
                        "properties": {
                            "min_eligible": {
                                "type": "integer"
                            },
                            "min_brands": {
                                "type": "integer"
                            },
                            "meets": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "rank": {
                                    "type": "integer"
                                },
                                "listing_id": {
                                    "type": "integer"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "city": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "state": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "profile_url": {
                                    "type": "string",
                                    "format": "url",
                                    "nullable": true
                                },
                                "ranking_score": {
                                    "type": "number"
                                },
                                "score": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "grade": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "rating": {
                                    "type": "number",
                                    "nullable": true
                                },
                                "reviews": {
                                    "type": "integer"
                                },
                                "last_12_months": {
                                    "type": "integer"
                                },
                                "sites": {
                                    "type": "array",
                                    "items": {
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            },
                                            "rating": {
                                                "type": "number",
                                                "nullable": true
                                            },
                                            "reviews": {
                                                "type": "integer"
                                            }
                                        },
                                        "type": "object"
                                    }
                                },
                                "why": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "movement": {
                                    "description": "`New`, `=`, `▲n` or `▼n` against the previous month; null without one.",
                                    "type": "string",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1DirectoryClaimListing": {
                "description": "The public facts of a listing a claim page shows. `claimed` reads the same for a claimed and a managed listing.",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "address": {
                        "type": "string",
                        "nullable": true
                    },
                    "city": {
                        "type": "string",
                        "nullable": true
                    },
                    "state": {
                        "type": "string",
                        "nullable": true
                    },
                    "category": {
                        "description": "Singular category name.",
                        "type": "string",
                        "nullable": true
                    },
                    "website": {
                        "type": "string",
                        "nullable": true
                    },
                    "profile_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "claimed": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1DirectoryClaimMethods": {
                "description": "The verification methods in the order the claim page offers them.",
                "properties": {
                    "gbp": {
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "reason": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "email": {
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "domain": {
                                "type": "string",
                                "nullable": true
                            },
                            "reason": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "site": {
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "website": {
                                "type": "string",
                                "nullable": true
                            },
                            "reason": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "phone": {
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "reason": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "review": {
                        "properties": {
                            "available": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1DirectoryClaim": {
                "description": "A claim as its claimer sees it. `next`: what the claim page shows.",
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "status": {
                        "type": "string"
                    },
                    "next": {
                        "type": "string",
                        "enum": [
                            "choose_method",
                            "enter_code",
                            "in_review",
                            "owner",
                            "closed"
                        ]
                    },
                    "method": {
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "description": "Masked.",
                        "type": "string",
                        "nullable": true
                    },
                    "code_expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "resend_available_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "attempts_left": {
                        "type": "integer",
                        "nullable": true
                    },
                    "locked_until": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "verified_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "listing": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1DirectoryClaimListing"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "methods": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1DirectoryClaimMethods"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "company": {
                        "description": "Uuid, once approved.",
                        "type": "string",
                        "nullable": true
                    },
                    "gbp": {
                        "properties": {
                            "status": {
                                "type": "string",
                                "nullable": true
                            },
                            "mismatches": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "locations_checked": {
                                "type": "integer",
                                "nullable": true
                            },
                            "checked_at": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "site": {
                        "description": "The website method while verifying: the snippets of the current token and the last check.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    }
                },
                "type": "object"
            },
            "V1FeedsMeta": {
                "properties": {
                    "formats": {
                        "description": "The feed formats.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "rss",
                                "atom",
                                "json"
                            ]
                        }
                    },
                    "parameters": {
                        "description": "The query parameters the feeds take, with a short explanation each.",
                        "properties": {
                            "sites": {
                                "type": "string"
                            },
                            "min_rating": {
                                "type": "string"
                            },
                            "since": {
                                "type": "string"
                            },
                            "limit": {
                                "type": "string"
                            },
                            "all_locations": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "cache_seconds": {
                        "description": "How long the feeds are cached.",
                        "type": "integer"
                    },
                    "keys": {
                        "description": "The company's active publishable keys, by prefix (never the full key).",
                        "type": "array",
                        "items": {
                            "properties": {
                                "id": {
                                    "type": "integer"
                                },
                                "name": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "prefix": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "docs": {
                        "type": "string",
                        "format": "uri"
                    }
                },
                "type": "object"
            },
            "V1HubClientCompany": {
                "description": "A Grades company linked to a Hub client (identity links only).",
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "customer",
                            "directory"
                        ]
                    },
                    "location_label": {
                        "description": "Location nickname, else \"City, ST\".",
                        "type": "string",
                        "nullable": true
                    },
                    "city": {
                        "type": "string",
                        "nullable": true
                    },
                    "state": {
                        "type": "string",
                        "nullable": true
                    },
                    "is_hq": {
                        "type": "boolean"
                    },
                    "hq_uuid": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "offboarded"
                        ]
                    },
                    "linked_via": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "hub_provisioned",
                                "directory_listing"
                            ]
                        }
                    },
                    "hub_location_key": {
                        "type": "string",
                        "nullable": true
                    },
                    "listing": {
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "profile_url": {
                                "type": "string",
                                "nullable": true
                            },
                            "published": {
                                "type": "boolean"
                            },
                            "status": {
                                "type": "string"
                            },
                            "claim_state": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "plan": {
                        "type": "string",
                        "example": "pro"
                    },
                    "premium": {
                        "description": "The company is on the Premium plan.",
                        "type": "boolean"
                    },
                    "billing": {
                        "properties": {
                            "mode": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string"
                            },
                            "locked": {
                                "type": "boolean"
                            },
                            "trial_ends_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "dashboard_url": {
                        "description": "`https://my.grades.com/?company=<uuid>`; null for a directory-only company.",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubClientMeta": {
                "description": "Meta of every Hub MCP read response.",
                "properties": {
                    "source": {
                        "type": "string",
                        "example": "grades.com"
                    },
                    "attribution": {
                        "type": "string",
                        "example": "Data from Grades.com"
                    },
                    "hub_client_id": {
                        "type": "string",
                        "example": "4950"
                    },
                    "companies_count": {
                        "type": "integer"
                    },
                    "premium": {
                        "description": "At least one company in scope is Premium.",
                        "type": "boolean"
                    },
                    "plans": {
                        "description": "Per company uuid: {plan, premium}.",
                        "type": "object",
                        "additionalProperties": {
                            "properties": {
                                "plan": {
                                    "type": "string"
                                },
                                "premium": {
                                    "type": "boolean"
                                }
                            },
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1HubClientReview": {
                "description": "A review for the Hub MCP.",
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "company": {
                        "description": "uuid, name, location_label, plan, premium, dashboard_url.",
                        "type": "object"
                    },
                    "site": {
                        "type": "string",
                        "example": "google"
                    },
                    "site_name": {
                        "type": "string",
                        "example": "Google"
                    },
                    "rating": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 5,
                        "minimum": 1
                    },
                    "published_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "author": {
                        "type": "string",
                        "nullable": true
                    },
                    "text": {
                        "description": "Excerpt, at most 500 characters.",
                        "type": "string",
                        "nullable": true
                    },
                    "text_truncated": {
                        "type": "boolean"
                    },
                    "text_withheld": {
                        "description": "The site allows rating and count only (Yelp).",
                        "type": "boolean"
                    },
                    "reply": {
                        "properties": {
                            "state": {
                                "type": "string",
                                "enum": [
                                    "replied",
                                    "none"
                                ]
                            },
                            "on_site": {
                                "type": "boolean"
                            },
                            "from_grades": {
                                "type": "boolean"
                            },
                            "replied_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "url": {
                        "type": "string",
                        "nullable": true
                    },
                    "dashboard_url": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubClientCompanyBrief": {
                "description": "The short company form of the Hub MCP reads.",
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "location_label": {
                        "type": "string",
                        "nullable": true
                    },
                    "plan": {
                        "type": "string",
                        "example": "pro"
                    },
                    "premium": {
                        "type": "boolean"
                    },
                    "dashboard_url": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubClientReviewMetrics": {
                "description": "Review counts of a period (removed reviews left out): all-time total and average, the period's new reviews, the previous period of the same length, replies, star distribution.",
                "properties": {
                    "reviews_total": {
                        "type": "integer"
                    },
                    "rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "new_reviews": {
                        "type": "integer"
                    },
                    "new_rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "previous_new_reviews": {
                        "type": "integer"
                    },
                    "previous_rating_average": {
                        "type": "number",
                        "nullable": true
                    },
                    "responded": {
                        "type": "integer"
                    },
                    "response_rate": {
                        "description": "Share of the new reviews answered on the site or from Grades; null without new reviews.",
                        "type": "number",
                        "nullable": true
                    },
                    "unanswered_negative": {
                        "type": "integer"
                    },
                    "rating_distribution": {
                        "properties": {
                            "5": {
                                "type": "integer"
                            },
                            "4": {
                                "type": "integer"
                            },
                            "3": {
                                "type": "integer"
                            },
                            "2": {
                                "type": "integer"
                            },
                            "1": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "pending_agent_actions": {
                        "type": "integer"
                    },
                    "low_ratings": {
                        "type": "integer"
                    },
                    "unanswered": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1HubLocation": {
                "description": "A Hub location: one Grades company, keyed by the Hub ID and a location key.",
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "hub_client_id": {
                        "type": "string",
                        "example": "4950"
                    },
                    "hub_location_key": {
                        "type": "string",
                        "example": "main"
                    },
                    "source": {
                        "type": "string",
                        "enum": [
                            "hub",
                            "self_serve"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "offboarded"
                        ]
                    },
                    "offboarded_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "name": {
                        "type": "string"
                    },
                    "location_nickname": {
                        "type": "string",
                        "nullable": true
                    },
                    "website": {
                        "type": "string",
                        "nullable": true
                    },
                    "phone": {
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "nullable": true
                    },
                    "timezone": {
                        "type": "string",
                        "example": "America/New_York",
                        "nullable": true
                    },
                    "address": {
                        "type": "object"
                    },
                    "billing": {
                        "properties": {
                            "mode": {
                                "type": "string",
                                "enum": [
                                    "stripe",
                                    "unconfigured"
                                ]
                            },
                            "plan": {
                                "type": "string",
                                "example": "pro"
                            },
                            "status": {
                                "type": "string",
                                "example": "trialing"
                            },
                            "locked": {
                                "type": "boolean"
                            },
                            "trial_ends_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "sources": {
                        "description": "`V1Source` plus `origin`: `hub` for the source the Hub pushes Google reviews into.",
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    },
                    "counts": {
                        "properties": {
                            "reviews": {
                                "type": "integer"
                            },
                            "average_rating": {
                                "type": "number",
                                "nullable": true
                            },
                            "agent_pending_actions": {
                                "type": "integer"
                            },
                            "users": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "users": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "email": {
                                    "type": "string"
                                },
                                "name": {
                                    "type": "string"
                                },
                                "role": {
                                    "type": "string",
                                    "enum": [
                                        "owner",
                                        "super_admin",
                                        "admin",
                                        "approver",
                                        "reviewer",
                                        "viewer",
                                        "user"
                                    ]
                                },
                                "invitation": {
                                    "type": "string",
                                    "enum": [
                                        "accepted",
                                        "pending"
                                    ]
                                }
                            },
                            "type": "object"
                        }
                    },
                    "links": {
                        "properties": {
                            "dashboard": {
                                "type": "string",
                                "format": "url"
                            }
                        },
                        "type": "object"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "V1WebhookEndpoint": {
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "url": {
                        "type": "string",
                        "format": "url"
                    },
                    "events": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "review.created",
                                "review.updated",
                                "review.removed",
                                "review.replied",
                                "agent.action.pending",
                                "agent.action.posted",
                                "source.reconnect_required",
                                "radar.mention.found",
                                "radar.ai_perception.changed",
                                "review_request.clicked",
                                "review_request.visited",
                                "review_request.reviewed",
                                "review_request.unsubscribed",
                                "recovery.case.opened",
                                "review.tagged"
                            ]
                        }
                    },
                    "company": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "scope": {
                        "type": "string",
                        "enum": [
                            "company",
                            "account"
                        ]
                    },
                    "active": {
                        "type": "boolean"
                    },
                    "description": {
                        "type": "string",
                        "nullable": true
                    },
                    "failure_count": {
                        "type": "integer"
                    },
                    "disabled_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_delivered_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "V1WebhookEndpointCreated": {
                "description": "A new webhook endpoint: the endpoint plus its signing `secret`, returned only here.",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1WebhookEndpoint"
                    },
                    {
                        "required": [
                            "secret"
                        ],
                        "properties": {
                            "secret": {
                                "description": "Signing secret (`whsec_...`). Only in the creation response.",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1HubDirectoryBadge": {
                "description": "The grade badge: hosted SVG URL and embed snippet (null without a public profile). `available`: a new embed may be offered (directory live, listing published, the latest score badge-eligible).",
                "properties": {
                    "available": {
                        "type": "boolean"
                    },
                    "svg_url": {
                        "type": "string",
                        "format": "url"
                    },
                    "snippet": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubDirectoryListing": {
                "description": "A directory listing of a Hub location: its state, public URL and badge.",
                "properties": {
                    "hub_location_key": {
                        "type": "string",
                        "nullable": true
                    },
                    "listing_id": {
                        "type": "integer"
                    },
                    "company_uuid": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "name": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "example": "active"
                    },
                    "hidden_reason": {
                        "description": "Why an import hid it (opt_out, not_active_seo, restricted, excluded); null = shown, or a person hid it.",
                        "type": "string",
                        "nullable": true
                    },
                    "claim_state": {
                        "type": "string",
                        "enum": [
                            "unclaimed",
                            "claimed",
                            "managed"
                        ]
                    },
                    "verification": {
                        "type": "string",
                        "enum": [
                            "unvalidated",
                            "validated",
                            "conflict"
                        ]
                    },
                    "published": {
                        "type": "boolean"
                    },
                    "profile_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "badge": {
                        "$ref": "#/components/schemas/V1HubDirectoryBadge"
                    },
                    "synced_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubDirectoryListingFacts": {
                "description": "A directory listing with the facts grades.com stores, the source of each published value (`provenance`, per field), the open name / address / phone `conflicts` and the Hub's review-site facts.",
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1HubDirectoryListing"
                    },
                    {
                        "properties": {
                            "address": {
                                "properties": {
                                    "line1": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "line2": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "city": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "state": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "zip": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "country": {
                                        "type": "string",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            },
                            "hide_address": {
                                "type": "boolean"
                            },
                            "service_area": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "phone": {
                                "oneOf": [
                                    {
                                        "$ref": "#/components/schemas/V1HubDirectoryPhone"
                                    },
                                    {
                                        "type": "object",
                                        "nullable": true,
                                        "enum": [
                                            null
                                        ]
                                    }
                                ]
                            },
                            "phone_alt": {
                                "oneOf": [
                                    {
                                        "$ref": "#/components/schemas/V1HubDirectoryPhone"
                                    },
                                    {
                                        "type": "object",
                                        "nullable": true,
                                        "enum": [
                                            null
                                        ]
                                    }
                                ]
                            },
                            "website": {
                                "type": "string",
                                "nullable": true
                            },
                            "hours": {
                                "description": "Business Profile shape (regular + special hours).",
                                "type": "object",
                                "nullable": true,
                                "additionalProperties": true
                            },
                            "categories": {
                                "properties": {
                                    "primary": {
                                        "oneOf": [
                                            {
                                                "$ref": "#/components/schemas/V1HubDirectoryCategory"
                                            },
                                            {
                                                "type": "object",
                                                "nullable": true,
                                                "enum": [
                                                    null
                                                ]
                                            }
                                        ]
                                    },
                                    "additional": {
                                        "type": "array",
                                        "items": {
                                            "$ref": "#/components/schemas/V1HubDirectoryCategory"
                                        }
                                    },
                                    "google": {
                                        "description": "The Google category ids of the published categories fact, as given.",
                                        "properties": {
                                            "primary": {
                                                "type": "string",
                                                "nullable": true
                                            },
                                            "additional": {
                                                "type": "array",
                                                "items": {
                                                    "type": "string"
                                                }
                                            }
                                        },
                                        "type": "object",
                                        "nullable": true
                                    }
                                },
                                "type": "object"
                            },
                            "provenance": {
                                "description": "Per published field: the source of its value.",
                                "type": "object",
                                "additionalProperties": {
                                    "properties": {
                                        "source": {
                                            "type": "string",
                                            "example": "hub"
                                        },
                                        "method": {
                                            "type": "string"
                                        },
                                        "updated_at": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "observed_at": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "confirmed_at": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "hub_agrees": {
                                            "description": "Whether the Hub's own value is the same; null when the Hub sent none.",
                                            "type": "boolean",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "conflicts": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "field": {
                                            "type": "string"
                                        },
                                        "our_value": {
                                            "description": "Any JSON value."
                                        },
                                        "our_source": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "their_value": {
                                            "description": "Any JSON value."
                                        },
                                        "their_source": {
                                            "type": "string"
                                        },
                                        "their_ref": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "opened_at": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "review_sites": {
                                "description": "The Hub's review-site facts. `fetched_by`: `grades` (a source of ours collects the reviews), `hub` (the Hub pushes them) or null (scored from the Hub's count only).",
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "site": {
                                            "type": "string"
                                        },
                                        "known": {
                                            "type": "boolean"
                                        },
                                        "url": {
                                            "type": "string",
                                            "nullable": true
                                        },
                                        "rating": {
                                            "type": "number",
                                            "nullable": true
                                        },
                                        "review_count": {
                                            "type": "integer",
                                            "nullable": true
                                        },
                                        "observed_at": {
                                            "type": "string",
                                            "format": "date-time",
                                            "nullable": true
                                        },
                                        "method": {
                                            "type": "string"
                                        },
                                        "fetched_by": {
                                            "type": "string",
                                            "nullable": true,
                                            "enum": [
                                                "grades",
                                                "hub"
                                            ]
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1HubDirectoryPhone": {
                "properties": {
                    "e164": {
                        "type": "string"
                    },
                    "display": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubDirectoryCategory": {
                "properties": {
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "name_singular": {
                        "type": "string"
                    },
                    "gcid": {
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubDirectoryBrand": {
                "description": "The Hub client's brand profile with its stored facts.",
                "properties": {
                    "brand_id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "scope": {
                        "type": "string",
                        "enum": [
                            "local",
                            "national",
                            "both"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "hidden",
                            "merged"
                        ]
                    },
                    "hidden_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "claim_state": {
                        "type": "string"
                    },
                    "profile_url": {
                        "type": "string",
                        "format": "url"
                    },
                    "website": {
                        "type": "string",
                        "nullable": true
                    },
                    "industry": {
                        "properties": {
                            "hub_value": {
                                "type": "string",
                                "example": "Retail & Ecommerce > Furniture"
                            },
                            "name": {
                                "type": "string"
                            },
                            "path": {
                                "type": "string"
                            },
                            "policy": {
                                "type": "string",
                                "enum": [
                                    "list",
                                    "restricted"
                                ]
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "short_description": {
                        "type": "string",
                        "nullable": true
                    },
                    "description": {
                        "type": "string",
                        "nullable": true
                    },
                    "logo_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "review_sites": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "provenance": {
                        "description": "Per brand field with a stored value (name, website, logo): the source of its fact.",
                        "type": "object",
                        "additionalProperties": {
                            "properties": {
                                "source": {
                                    "type": "string"
                                },
                                "method": {
                                    "type": "string"
                                },
                                "updated_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                },
                                "observed_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        }
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1HubDirectoryPushMeta": {
                "description": "`received` and one count per result `status`.",
                "properties": {
                    "received": {
                        "type": "integer"
                    }
                },
                "type": "object",
                "additionalProperties": {
                    "type": "integer"
                }
            },
            "V1HubInvitation": {
                "description": "A portal user invitation (`email` lower-cased).",
                "properties": {
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "role": {
                        "type": "string",
                        "enum": [
                            "admin",
                            "user"
                        ]
                    },
                    "invitation": {
                        "type": "string",
                        "enum": [
                            "sent",
                            "existing_user_pending",
                            "already_member"
                        ]
                    }
                },
                "type": "object"
            },
            "V1ReviewShowcase": {
                "properties": {
                    "id": {
                        "description": "The saved showcase id.",
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "style": {
                        "type": "string",
                        "enum": [
                            "light",
                            "dark",
                            "auto"
                        ]
                    },
                    "rules": {
                        "$ref": "#/components/schemas/V1ShowcaseRules"
                    },
                    "embed": {
                        "description": "Snippets: `iframe`, `script`, `wordpress`, `url`.",
                        "properties": {
                            "url": {
                                "description": "The hosted embed page.",
                                "type": "string"
                            },
                            "iframe": {
                                "type": "string"
                            },
                            "script": {
                                "type": "string"
                            },
                            "wordpress": {
                                "description": "The WordPress plugin shortcode.",
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "yelp_consent": {
                        "description": "Who confirmed the Yelp terms notice for this showcase: `at`, `version`; null when nobody did.",
                        "properties": {
                            "at": {
                                "type": "string",
                                "format": "date-time"
                            },
                            "version": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SavedChange": {
                "properties": {
                    "action": {
                        "description": "`yelp_consent` (saved showcases only): the Yelp terms notice was confirmed.",
                        "type": "string",
                        "enum": [
                            "created",
                            "updated",
                            "deleted",
                            "yelp_consent"
                        ]
                    },
                    "user_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "before": {
                        "description": "The saved fields before the change; null for `created`.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "after": {
                        "description": "The saved fields after the change; null for `deleted`.",
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SavedWidgetInput": {
                "properties": {
                    "name": {
                        "description": "Required when saving.",
                        "type": "string",
                        "maxLength": 80,
                        "minLength": 1
                    },
                    "preset": {
                        "type": "string",
                        "enum": [
                            "pill",
                            "strip",
                            "carousel",
                            "grid",
                            "list",
                            "masonry",
                            "spotlight",
                            "summary",
                            "wall",
                            "video",
                            "badge",
                            "popup",
                            "tab",
                            "button"
                        ]
                    },
                    "settings": {
                        "description": "Snippet options by name (as in `GET /v1/companies/{company}/widget`); strings, integers or booleans (on / off). Unknown names are dropped; a bad value is 422 `invalid_widget_option`. Stored as the non-default values.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "custom_css": {
                        "description": "Premium only (402 otherwise): at most 4 KB; no @import, no url() except data: images, no expression, no \"<\", no position: fixed outside floating presets (422 `invalid_custom_css`). Empty or null removes it.",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SavedWidget": {
                "properties": {
                    "id": {
                        "description": "The `widget_id` a snippet names.",
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "preset": {
                        "type": "string",
                        "enum": [
                            "pill",
                            "strip",
                            "carousel",
                            "grid",
                            "list",
                            "masonry",
                            "spotlight",
                            "summary",
                            "wall",
                            "video",
                            "badge",
                            "popup",
                            "tab",
                            "button"
                        ]
                    },
                    "settings": {
                        "description": "The snippet options that differ from the defaults, by option name (booleans as on / off).",
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    },
                    "custom_css": {
                        "description": "Premium custom CSS as stored (kept while the plan has none).",
                        "type": "string",
                        "nullable": true
                    },
                    "custom_css_active": {
                        "description": "True when the custom CSS is drawn (Premium, and it passes the checks).",
                        "type": "boolean"
                    },
                    "translate": {
                        "description": "The `translate` setting is on.",
                        "type": "boolean"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ShowcaseMeta": {
                "description": "OpenAPI schema `V1ShowcaseMeta` of the Review Showcase endpoints (docs/showcase.md). One class per schema:\nswagger-php nests a second class-level schema or a sibling parameter into the first.",
                "properties": {
                    "business": {
                        "properties": {
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "all_reviews": {
                        "description": "The directory profile or the review page; null when neither exists.",
                        "type": "object",
                        "nullable": true
                    },
                    "yelp_text_included": {
                        "description": "True when Yelp reviews with text are in `data` (after `yelp_consent`; for internal use only).",
                        "type": "boolean"
                    },
                    "rules": {
                        "type": "object"
                    },
                    "returned": {
                        "type": "integer"
                    },
                    "eligible": {
                        "type": "integer"
                    },
                    "topic": {
                        "type": "object",
                        "nullable": true
                    },
                    "fallback": {
                        "description": "`reason`: too_few_matches or clinical_terms.",
                        "type": "object",
                        "nullable": true
                    },
                    "excluded": {
                        "description": "Reviews left out, by reason.",
                        "type": "object"
                    },
                    "generated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "rendered": {
                        "description": "The formats `include` asked for.",
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ShowcaseReview": {
                "properties": {
                    "uuid": {
                        "description": "The review uuid.",
                        "type": "string",
                        "format": "uuid"
                    },
                    "rating": {
                        "type": "integer",
                        "maximum": 5,
                        "minimum": 1
                    },
                    "text": {
                        "description": "As written; never shortened.",
                        "type": "string"
                    },
                    "author": {
                        "description": "First name and initial (\"Jane D.\").",
                        "type": "string"
                    },
                    "site": {
                        "type": "string",
                        "example": "Google"
                    },
                    "site_key": {
                        "type": "string",
                        "example": "google"
                    },
                    "published_at": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "url": {
                        "description": "The review on its site.",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ShowcaseRules": {
                "properties": {
                    "count": {
                        "description": "Most reviews shown.",
                        "type": "integer",
                        "maximum": 50,
                        "minimum": 1
                    },
                    "min_rating": {
                        "type": "integer",
                        "maximum": 5,
                        "minimum": 1
                    },
                    "min_length": {
                        "type": "integer",
                        "maximum": 2000,
                        "minimum": 0
                    },
                    "max_length": {
                        "type": "integer",
                        "maximum": 5000,
                        "minimum": 40
                    },
                    "topic": {
                        "type": "string",
                        "nullable": true
                    },
                    "sites": {
                        "description": "Site keys; empty = every eligible site.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "max_age_days": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 3650,
                        "minimum": 1
                    },
                    "language": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "en",
                            "es",
                            "fr",
                            "pt",
                            "de",
                            "it"
                        ]
                    },
                    "seed": {
                        "type": "string",
                        "nullable": true
                    },
                    "tags": {
                        "description": "Review tag slugs (any of them); empty = no tag filter.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "type": "object"
            },
            "Problem": {
                "description": "RFC 7807 problem details (`application/problem+json`).",
                "required": [
                    "type",
                    "title",
                    "status"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "example": "about:blank"
                    },
                    "title": {
                        "type": "string",
                        "example": "Not Found"
                    },
                    "status": {
                        "type": "integer",
                        "example": 404
                    },
                    "detail": {
                        "type": "string",
                        "example": "Company Not Found"
                    },
                    "errors": {
                        "description": "Validation errors by parameter.",
                        "type": "object",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                },
                "type": "object"
            },
            "V1WidgetCard": {
                "properties": {
                    "uuid": {
                        "description": "The review uuid (`demo-<n>` on the demo widget).",
                        "type": "string"
                    },
                    "rating": {
                        "type": "integer",
                        "maximum": 5,
                        "minimum": 1
                    },
                    "author": {
                        "description": "First name and initial.",
                        "type": "string"
                    },
                    "initial": {
                        "type": "string"
                    },
                    "site": {
                        "description": "The review site's name; empty for a review added through the API.",
                        "type": "string"
                    },
                    "site_key": {
                        "type": "string"
                    },
                    "site_icon_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "published_at": {
                        "type": "string",
                        "nullable": true
                    },
                    "date_label": {
                        "type": "string",
                        "nullable": true
                    },
                    "text": {
                        "description": "As written; never shortened.",
                        "type": "string"
                    },
                    "text_short": {
                        "description": "The first characters, cut at a word.",
                        "type": "string"
                    },
                    "truncated": {
                        "description": "True when `text_short` is shorter than `text`.",
                        "type": "boolean"
                    },
                    "reply": {
                        "description": "With `show_reply` only: the business's public reply when it may be quoted.",
                        "type": "string",
                        "nullable": true
                    },
                    "video": {
                        "description": "Video preset only: the Reviews on Grades.com video of the review.",
                        "properties": {
                            "url": {
                                "type": "string"
                            },
                            "mime": {
                                "type": "string",
                                "nullable": true
                            },
                            "width": {
                                "type": "integer",
                                "nullable": true
                            },
                            "height": {
                                "type": "integer",
                                "nullable": true
                            },
                            "duration_seconds": {
                                "type": "number",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "translation": {
                        "description": "Widgets v2 `translate=on`: a stored machine translation of `text` (`text`, `from` language).",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "reply_translation": {
                        "description": "Widgets v2 `translate=on`: a stored machine translation of `reply`.",
                        "type": "object",
                        "additionalProperties": true
                    }
                },
                "type": "object"
            },
            "V1WidgetData": {
                "properties": {
                    "preset": {
                        "description": "The widget preset.",
                        "type": "string",
                        "enum": [
                            "pill",
                            "strip",
                            "carousel",
                            "grid",
                            "list",
                            "masonry",
                            "spotlight",
                            "summary",
                            "wall",
                            "video",
                            "badge",
                            "popup",
                            "tab",
                            "button"
                        ]
                    },
                    "theme": {
                        "type": "string",
                        "enum": [
                            "light",
                            "dark",
                            "auto"
                        ]
                    },
                    "accent": {
                        "description": "Hex color (the snippet's, else the review page's, else the default).",
                        "type": "string"
                    },
                    "business": {
                        "properties": {
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "summary": {
                        "description": "The true rating and review count (never narrowed by the filters); null without a rating.",
                        "properties": {
                            "average": {
                                "type": "number"
                            },
                            "average_label": {
                                "type": "string"
                            },
                            "count": {
                                "type": "integer"
                            },
                            "count_label": {
                                "type": "string"
                            },
                            "sites": {
                                "description": "Per-site totals, most reviews first (`key`, `name`, `count`, `average`, `average_label`, `icon_url`).",
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "additionalProperties": true
                                }
                            },
                            "more_sites": {
                                "description": "Sites beyond the ones listed.",
                                "type": "integer"
                            },
                            "rating_word": {
                                "description": "excellent, great or good; null below the thresholds or under the minimum review count (10 by default).",
                                "type": "string",
                                "nullable": true
                            },
                            "scope": {
                                "description": "Widgets v2: the visitor's site tab these totals are for (`site`, `name`).",
                                "type": "object",
                                "additionalProperties": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "grade": {
                        "description": "The Grades.com grade badge; null without one.",
                        "properties": {
                            "badge_url": {
                                "type": "string"
                            },
                            "badge_url_dark": {
                                "description": "Demo only.",
                                "type": "string"
                            },
                            "alt": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "source": {
                        "description": "The single site's mark when `sites` names one site with a rating; null for the Grades.com mark.",
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "icon_url": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "reviews": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1WidgetCard"
                        }
                    },
                    "link": {
                        "description": "Where the widget links (all reviews; the review button: the review page); null without one.",
                        "properties": {
                            "url": {
                                "type": "string"
                            },
                            "kind": {
                                "type": "string"
                            },
                            "label": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "display": {
                        "description": "The resolved options of the widget.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "filtered": {
                        "description": "True when a review tag filter applies (absent on the demo).",
                        "type": "boolean"
                    },
                    "filters": {
                        "description": "What narrows the cards: min_rating, sites, tags; empty = every review the Showcase rules allow.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "min_rating",
                                "sites",
                                "tags"
                            ]
                        }
                    },
                    "preview": {
                        "description": "Company endpoint only: always true (the dashboard preview).",
                        "type": "boolean"
                    },
                    "demo": {
                        "description": "Demo widget only: always true.",
                        "type": "boolean"
                    },
                    "ai_summary": {
                        "description": "Widgets v2 `show_summary=on`: the approved AI summary line; null when none is approved.",
                        "properties": {
                            "text": {
                                "type": "string"
                            },
                            "review_count": {
                                "type": "integer"
                            },
                            "lang": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "controls": {
                        "description": "Widgets v2 with `controls`: the visitor controls and their choices.",
                        "type": "object",
                        "additionalProperties": true
                    },
                    "page": {
                        "description": "Widgets v2 with `controls`: the page of reviews shown.",
                        "properties": {
                            "number": {
                                "type": "integer"
                            },
                            "size": {
                                "type": "integer"
                            },
                            "has_more": {
                                "type": "boolean"
                            },
                            "total": {
                                "type": "integer"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "site_panel": {
                        "description": "Widgets v2: the rating panel of a site tab whose text is not shown (Yelp).",
                        "type": "object",
                        "additionalProperties": true
                    }
                },
                "type": "object"
            },
            "V1WidgetEmbed": {
                "properties": {
                    "url": {
                        "description": "The hosted widget page.",
                        "type": "string"
                    },
                    "script": {
                        "description": "The loader script snippet.",
                        "type": "string"
                    },
                    "element": {
                        "description": "The `<grades-widget>` custom element snippet with its script.",
                        "type": "string"
                    },
                    "iframe": {
                        "description": "The iframe snippet; null for floating presets.",
                        "type": "string",
                        "nullable": true
                    },
                    "wordpress": {
                        "description": "The WordPress plugin shortcode.",
                        "type": "string"
                    },
                    "ref": {
                        "description": "The publishable key or saved showcase id in the snippets (or the placeholder).",
                        "type": "string"
                    },
                    "placeholder": {
                        "description": "True when `ref` is the placeholder, not a real key.",
                        "type": "boolean"
                    },
                    "floating": {
                        "description": "True for presets that float over the page (badge, popup, tab).",
                        "type": "boolean"
                    },
                    "png": {
                        "description": "Pill only: the URL of the PNG image twin; null otherwise.",
                        "type": "string",
                        "nullable": true
                    },
                    "svg": {
                        "description": "Pill only: the URL of the SVG image twin; null otherwise.",
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "description": "Pill only, with a link and an image size: the e-mail signature snippet (the PNG in a link).",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1WidgetSummaryMeta": {
                "properties": {
                    "generating": {
                        "description": "Always false: generation runs within the request.",
                        "type": "boolean"
                    },
                    "can_generate": {
                        "description": "The caller may change widgets and the monthly budget allows a call.",
                        "type": "boolean"
                    },
                    "copy": {
                        "description": "The explanation line the dashboard shows.",
                        "type": "string"
                    },
                    "max_text": {
                        "description": "Most characters of the line.",
                        "type": "integer"
                    },
                    "budget": {
                        "description": "The monthly AI budget of the summaries.",
                        "properties": {
                            "monthly_usd": {
                                "type": "number"
                            },
                            "spent_usd": {
                                "type": "number"
                            }
                        },
                        "type": "object"
                    },
                    "result": {
                        "description": "Generate only: what the request did.",
                        "type": "string",
                        "enum": [
                            "created",
                            "unchanged",
                            "budget",
                            "failed",
                            "no_reviews"
                        ]
                    }
                },
                "type": "object"
            },
            "V1WidgetSummary": {
                "properties": {
                    "id": {
                        "description": "The version id (approve, reject).",
                        "type": "integer"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "draft",
                            "approved",
                            "rejected"
                        ]
                    },
                    "lang": {
                        "type": "string",
                        "enum": [
                            "en",
                            "es"
                        ]
                    },
                    "text": {
                        "description": "The one-line summary.",
                        "type": "string"
                    },
                    "topics": {
                        "description": "What customers mention, as short phrases.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "review_count": {
                        "description": "The reviews the summary was made from.",
                        "type": "integer"
                    },
                    "model": {
                        "description": "The model name, or `manual` for the owner's own text.",
                        "type": "string"
                    },
                    "manual": {
                        "description": "True when the owner wrote the line.",
                        "type": "boolean"
                    },
                    "based_on_id": {
                        "description": "The version an owner's edit started from.",
                        "type": "integer",
                        "nullable": true
                    },
                    "approved_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "rejected_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1WidgetSummaryState": {
                "properties": {
                    "lang": {
                        "description": "The language of the summary.",
                        "type": "string",
                        "enum": [
                            "en",
                            "es"
                        ]
                    },
                    "approved": {
                        "description": "What widgets show (`show_summary`); null when no version is approved.",
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/V1WidgetSummary"
                            }
                        ]
                    },
                    "draft": {
                        "description": "A version newer than the approved one, awaiting the owner; null when there is none.",
                        "nullable": true,
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/V1WidgetSummary"
                            }
                        ]
                    },
                    "history": {
                        "description": "Every version, newest first.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1WidgetSummary"
                        }
                    }
                },
                "type": "object"
            },
            "V1AgentActionReview": {
                "required": [
                    "uuid",
                    "source",
                    "rating",
                    "text",
                    "username",
                    "published_date",
                    "external_url",
                    "can_push_reply"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "source": {
                        "description": "The collector that stored the review: an internal id (`yelp_apify`, `google_maps`, `api`, ...) that may change. Show and filter by `site`.",
                        "type": "string",
                        "example": "google"
                    },
                    "site": {
                        "description": "The review platform (`google`, `yelp`, `direct`, ...), as on V1Review.",
                        "type": "string",
                        "example": "google"
                    },
                    "source_name": {
                        "description": "Display name of the platform.",
                        "type": "string",
                        "example": "Google"
                    },
                    "site_name": {
                        "description": "The name owners read for the review's site, as on V1Review: the brand (\"Google\"), \"Reviews on Grades.com\", \"Added via API\" or \"Imported\" (a file import).",
                        "type": "string",
                        "example": "Google"
                    },
                    "source_kind": {
                        "description": "As on V1Review: site | grades | own_system | unknown.",
                        "type": "string",
                        "enum": [
                            "site",
                            "grades",
                            "own_system",
                            "unknown"
                        ]
                    },
                    "source_phrase": {
                        "description": "As on V1Review: where the review is from in words (\"on Google\", \"from your WooCommerce store\", \"source not given (added through the API)\").",
                        "type": "string"
                    },
                    "origin_name": {
                        "description": "As on V1Review.",
                        "type": "string",
                        "nullable": true
                    },
                    "arrival": {
                        "description": "As on V1Review: collected | hub | api | import | review_page.",
                        "type": "string"
                    },
                    "rating": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 5,
                        "minimum": 1
                    },
                    "text": {
                        "description": "The first 300 characters.",
                        "type": "string",
                        "nullable": true
                    },
                    "username": {
                        "type": "string",
                        "nullable": true
                    },
                    "author": {
                        "description": "The same name as `username`, under the V1Review field name (what integrations map).",
                        "type": "string",
                        "nullable": true
                    },
                    "published_date": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "external_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "can_push_reply": {
                        "description": "The review site has a reply API (Google), so Grades can post replies to it.",
                        "type": "boolean"
                    },
                    "language": {
                        "description": "The review's language (ISO 639-1), null when unknown.",
                        "type": "string",
                        "nullable": true
                    },
                    "text_en": {
                        "description": "Machine translation of the whole review into English (\"Translated by AI\"; null when not needed, not made yet or not allowed).",
                        "type": "string",
                        "nullable": true
                    },
                    "translation": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1Translation"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "text_policy": {
                        "description": "`aggregate`: a Yelp review whose `text`, `username`, `author` and translation are withheld, and whose words are withheld from the whole action too (evidence, excerpts and quotes in drafts, rationale and result read \"[Yelp review text withheld]\"); send `yelp_consent=true` after recording the Yelp consent, as on V1Review. `yelp_consent`: included after consent, for internal use only. Null for every other review.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "aggregate",
                            "yelp_consent"
                        ]
                    },
                    "text_hint": {
                        "description": "Why the text is withheld and how to get it, else null.",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgentAction": {
                "required": [
                    "uuid",
                    "type",
                    "status",
                    "review",
                    "draft_text",
                    "flag_reason",
                    "policy_findings",
                    "classification",
                    "rationale",
                    "escalation",
                    "auto_post_after",
                    "model",
                    "can_publish",
                    "manual_url",
                    "executed_at",
                    "executed_by",
                    "execution",
                    "evidence_url",
                    "result",
                    "error",
                    "created_at",
                    "updated_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "reply",
                            "flag"
                        ]
                    },
                    "status": {
                        "description": "pending -> approved -> executed | failed (a failed action can be approved again); pending -> rejected | expired (after 14 days).",
                        "type": "string",
                        "enum": [
                            "pending",
                            "approved",
                            "rejected",
                            "executed",
                            "failed",
                            "expired",
                            "skipped"
                        ]
                    },
                    "review": {
                        "$ref": "#/components/schemas/V1AgentActionReview"
                    },
                    "draft_text": {
                        "description": "reply: the drafted reply (null when no draft could be written, see `error`); flag: the drafted report text for the site's form.",
                        "type": "string",
                        "nullable": true
                    },
                    "reply_language": {
                        "description": "reply: the language of the reply (the draft's, else the one the business's reply language setting asks for); null when unknown.",
                        "type": "string",
                        "nullable": true
                    },
                    "draft_language": {
                        "description": "The language of `draft_text`, null when it cannot be told.",
                        "type": "string",
                        "nullable": true
                    },
                    "draft_en": {
                        "description": "reply: machine translation of a non-English `draft_text` into English (\"Translated by AI\"), or the owner's own English when the text came from \"Translate my edit\"; null when not needed or not made.",
                        "type": "string",
                        "nullable": true
                    },
                    "draft_translation": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1Translation"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ]
                    },
                    "draft_withheld": {
                        "description": "flag: `plan` when the drafted report (`draft_text`, `result.next_steps`, `report.filed_as`) is withheld because the plan lacks drafted reports (Premium); the verdict (`flag_reason`, `policy_findings`, `report.ground` / `evidence` / `site_reason`, `rationale`) is still there and approving answers 402 `agent:flag_drafts`. Null otherwise.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "plan"
                        ]
                    },
                    "flag_reason": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "not_a_customer",
                            "competitor",
                            "spam",
                            "off_topic",
                            "harassment",
                            "pii",
                            "conflict_of_interest",
                            "duplicate",
                            "fake",
                            "policy_other"
                        ]
                    },
                    "policy_findings": {
                        "properties": {
                            "likelihood": {
                                "type": "number",
                                "format": "float",
                                "maximum": 1,
                                "minimum": 0
                            },
                            "site": {
                                "type": "string",
                                "example": "google"
                            },
                            "clauses": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "guideline": {
                                            "type": "string",
                                            "example": "conflict_of_interest"
                                        },
                                        "excerpt": {
                                            "type": "string"
                                        },
                                        "why": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "generic_grounds": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "classification": {
                        "properties": {
                            "sentiment": {
                                "type": "string",
                                "enum": [
                                    "positive",
                                    "neutral",
                                    "negative",
                                    "mixed"
                                ]
                            },
                            "urgency": {
                                "type": "string",
                                "enum": [
                                    "low",
                                    "normal",
                                    "high"
                                ]
                            },
                            "topics": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "rationale": {
                        "type": "string",
                        "nullable": true
                    },
                    "rationale_parts": {
                        "description": "The rationale without what other fields carry (urgency, topics, policy risk, reply API, escalation): `summary`; `needs_review` (`reason` rules|unchecked|other, `rules` of {code, detail} with the reply-rule codes breaks_rules, clinical_details, contact_details, wrong_language, staff_name, patient_relationship, review_solicitation, signature), null when the draft needs no extra read; `withheld` (auto-post refusal: draft_too_long, draft_has_email, draft_has_url, draft_has_phone, review_has_url, review_has_instructions) and `redrafted_on` (date). Null without a rationale.",
                        "properties": {
                            "summary": {
                                "type": "string"
                            },
                            "needs_review": {
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "enum": [
                                            "rules",
                                            "unchecked",
                                            "other"
                                        ]
                                    },
                                    "rules": {
                                        "type": "array",
                                        "items": {
                                            "properties": {
                                                "code": {
                                                    "type": "string"
                                                },
                                                "detail": {
                                                    "type": "string"
                                                }
                                            },
                                            "type": "object"
                                        }
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            },
                            "withheld": {
                                "type": "string",
                                "nullable": true
                            },
                            "redrafted_on": {
                                "type": "string",
                                "format": "date",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "escalation": {
                        "description": "Reply mode `auto_all` only: why the agent did not post this reply by itself and kept it for a person (codes: low_rating, unknown_rating, negative_sentiment, urgent, legal, medical, safety, discrimination, threat, refund_billing, staff_named, not_a_customer, policy_risk, policy_unchecked, flagged, needs_review, no_draft, unsafe_content, check_failed). Null when not escalated.",
                        "properties": {
                            "reasons": {
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "code": {
                                            "type": "string",
                                            "example": "low_rating"
                                        },
                                        "label": {
                                            "type": "string",
                                            "example": "Low rating"
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "at": {
                                "type": "string",
                                "format": "date-time"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "report": {
                        "description": "Removal reports decided by the engine (report mode `auto`, docs/review-agent.md 3.9): `ground`, `confidence`, `evidence` (quotes from the review), `site`, `site_reason`, `assertiveness`, `approval`, `hands_free`, `decided_at`; a `skipped` action has `skip_reason` and its reason in `rationale`. Null for other actions.",
                        "type": "object",
                        "nullable": true
                    },
                    "approved_by": {
                        "description": "`system`: a removal report filed without a person under the business's rules; `user:<uuid>`.",
                        "type": "string",
                        "nullable": true
                    },
                    "waiting_for": {
                        "description": "`login`: an approved report waits for you to connect your account on its site (`GET .../agent/login-requests`).",
                        "type": "string",
                        "nullable": true
                    },
                    "auto_post_after": {
                        "description": "Reply mode `auto_all`: a checked reply waiting for the end of the quiet hours or the next day's cap; the agent posts it then (unless someone approves or rejects it first).",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "model": {
                        "type": "string",
                        "example": "gemini-2.5-flash",
                        "nullable": true
                    },
                    "can_publish": {
                        "description": "reply: the review site has a reply API (Google), so approving can post it.",
                        "type": "boolean"
                    },
                    "manual_url": {
                        "description": "reply on a site without a reply API: where to paste the approved reply.",
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "handling": {
                        "$ref": "#/components/schemas/V1ReviewHandling"
                    },
                    "executed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "executed_by": {
                        "description": "`agent` or `user:<uuid>` (for rejected actions: who rejected it).",
                        "type": "string",
                        "nullable": true
                    },
                    "execution": {
                        "description": "How the action was carried out once approved: `api` (posted through the site API, Google), `manual` (stored in Grades: post it yourself at `manual_url` or follow `next_steps`), `browser` (review agent v2: carried out in your connected account; while `status` is `approved` it is queued or running). Null before approval.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "api",
                            "manual",
                            "browser",
                            "email"
                        ]
                    },
                    "evidence_url": {
                        "description": "`browser` only: API URL listing the screenshots taken before and after (signed links).",
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "result": {
                        "description": "reply: the `V1Reply` result (`status`, `manual_url`, `push_error`, ...); flag: `flag_id`, `flag_uuid`, `next_steps`, `report` (`V1ReportOutcome` plus `flag_status`: filed, removed, still live), and `removed_at` / `removal_reason` of the review (null while it is still on its site) plus `outcome` (`removed_by_platform`, or `restored` when it came back) once Grades saw the review disappear; rejected: `reason` and `reason_code`.",
                        "type": "object",
                        "nullable": true
                    },
                    "error": {
                        "description": "Why it failed, or why a reply has no draft: `ai_cap` (monthly AI drafts used), `ai_settings_incomplete`, `ai_error`.",
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "AgentBacktest": {
                "description": "A review agent test run (docs/review-agent.md 3.14) and, per review, what was actually replied next to what the agent\nwould have written. The review's text follows $gate exactly as the agent's actions do ({@see AgentActionResource}):\nthe dashboard session shows it to the owner; an API key or MCP token would get Yelp text withheld, with every quote of\nit in the draft, report and notes replaced by {@see YelpQuoteRedactor::MARKER}.",
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "pending",
                            "running",
                            "done",
                            "failed"
                        ]
                    },
                    "test_run": {
                        "description": "Always true: nothing of a test run was posted or saved as a draft.",
                        "type": "boolean"
                    },
                    "label": {
                        "type": "string",
                        "example": "Test run, nothing was posted"
                    },
                    "review_limit": {
                        "type": "integer"
                    },
                    "settings_source": {
                        "description": "`saved`, or `unsaved` (settings from the form, not saved).",
                        "type": "string"
                    },
                    "reviews_total": {
                        "type": "integer"
                    },
                    "reviews_done": {
                        "type": "integer"
                    },
                    "error": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "finished_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "expires_at": {
                        "description": "When the run and its results are deleted.",
                        "type": "string",
                        "format": "date-time"
                    },
                    "items": {
                        "description": "Only on `GET .../agent/backtests/{backtest}`.",
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    }
                },
                "type": "object"
            },
            "V1AgentLearning": {
                "required": [
                    "uuid",
                    "scope",
                    "kind",
                    "statement",
                    "status",
                    "origin",
                    "evidence",
                    "created_at",
                    "last_seen_at",
                    "decided_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "scope": {
                        "type": "string",
                        "enum": [
                            "business"
                        ]
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "length",
                            "sign_off",
                            "phrase_use",
                            "phrase_avoid",
                            "tone",
                            "content",
                            "escalation",
                            "fleet_override"
                        ]
                    },
                    "statement": {
                        "description": "What the agent does because of it.",
                        "type": "string"
                    },
                    "status": {
                        "description": "`active`: learned and applied, not reviewed yet; `accepted`: confirmed by a person (never retired); `dismissed`: turned off (never applied or learned again); `retired`: the outcomes no longer show it.",
                        "type": "string",
                        "enum": [
                            "active",
                            "accepted",
                            "dismissed",
                            "retired"
                        ]
                    },
                    "origin": {
                        "description": "`rules` (counted) or `model` (read by the agent model).",
                        "type": "string"
                    },
                    "evidence": {
                        "description": "Counts behind it (e.g. `edits`, `decisions`).",
                        "type": "object",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_seen_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "decided_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1FleetLearning": {
                "required": [
                    "uuid",
                    "scope",
                    "kind",
                    "statement",
                    "applied",
                    "override",
                    "stats",
                    "where",
                    "computed_on"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "scope": {
                        "type": "string",
                        "enum": [
                            "fleet"
                        ]
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "reply_pattern",
                            "escalation_rule",
                            "escalation_trigger",
                            "report_reason",
                            "site_conversion",
                            "improvement"
                        ]
                    },
                    "statement": {
                        "type": "string"
                    },
                    "applied": {
                        "description": "Used in draft prompts (reply patterns) or reply mode auto_all (escalation rules) of every business that did not turn it off; otherwise shown only.",
                        "type": "boolean"
                    },
                    "override": {
                        "description": "This business turned it off (`dismissed`) or confirmed it (`accepted`); null when it decided nothing.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "accepted",
                            "dismissed"
                        ]
                    },
                    "stats": {
                        "description": "Counts and rates across businesses.",
                        "type": "object"
                    },
                    "where": {
                        "description": "Site, category, rating band, language... it is about.",
                        "type": "object"
                    },
                    "computed_on": {
                        "type": "string",
                        "format": "date"
                    }
                },
                "type": "object"
            },
            "V1AgentSettings": {
                "required": [
                    "enabled",
                    "reply_mode",
                    "auto_post_min_rating",
                    "escalate_max_rating",
                    "auto_reply_daily_cap",
                    "quiet_hours_start",
                    "quiet_hours_end",
                    "flag_mode",
                    "flag_threshold",
                    "browser_automation",
                    "include_contact_details",
                    "contact_signoff",
                    "contact_signoff_phone",
                    "contact_signoff_email",
                    "tone",
                    "custom_instructions",
                    "last_triaged_at",
                    "updated_at",
                    "report_mode",
                    "report_rules",
                    "reports_consent",
                    "reply_voice",
                    "reply_signature",
                    "auto_post_languages",
                    "reply_language_mode",
                    "reply_languages",
                    "rules"
                ],
                "properties": {
                    "enabled": {
                        "description": "The agent triages new reviews every 10 minutes.",
                        "type": "boolean",
                        "default": false
                    },
                    "reply_mode": {
                        "description": "`off`: no reply drafts; `draft`: drafts, an approved reply is stored in Grades only (post it yourself, `manual_url`); `approve`: an approved reply is posted where the site has a reply API (Google); `auto_positive`: like `approve`, and replies to reviews rated >= `auto_post_min_rating` with a low policy risk (< 0.3) are posted at once on Google unless the escalation checks of `auto_all` keep them for a person (same `escalation.reasons`); `auto_all` (Premium, \"auto-reply to all reviews\"): like `approve`, and every reply on a site with a reply API (Google) is posted by the agent unless the review is escalated (kept as a pending draft with `escalation.reasons`): rated `escalate_max_rating` or lower, no rating, negative or urgent, legal / medical / safety / discrimination / threat wording, a refund or billing dispute, a staff member named, possibly not a customer, a policy risk or flag, or any reply rule or check that failed or could not run. Posts wait for the end of the quiet hours and stop at `auto_reply_daily_cap` a day.",
                        "type": "string",
                        "default": "draft",
                        "enum": [
                            "off",
                            "draft",
                            "approve",
                            "auto_positive",
                            "auto_all"
                        ]
                    },
                    "auto_post_min_rating": {
                        "type": "integer",
                        "default": 4,
                        "maximum": 5,
                        "minimum": 1
                    },
                    "escalate_max_rating": {
                        "description": "`auto_all` and `auto_positive`: reviews rated this or lower are never auto-replied (escalated); 0 = no rating escalation (approval `none`; every other escalation rule still holds).",
                        "type": "integer",
                        "default": 2,
                        "maximum": 4,
                        "minimum": 0
                    },
                    "auto_reply_daily_cap": {
                        "description": "`auto_all`: replies the agent posts by itself per day (company local time); the rest wait for the next day.",
                        "type": "integer",
                        "default": 20,
                        "maximum": 200,
                        "minimum": 1
                    },
                    "quiet_hours_start": {
                        "description": "`auto_all`: local hour (0-23, `meta.timezone`) from which the agent does not post; null with `quiet_hours_end` null = no quiet hours. Replies due then are posted when they end.",
                        "type": "integer",
                        "nullable": true,
                        "maximum": 23,
                        "minimum": 0
                    },
                    "quiet_hours_end": {
                        "description": "`auto_all`: local hour (0-23) the quiet hours end.",
                        "type": "integer",
                        "nullable": true,
                        "maximum": 23,
                        "minimum": 0
                    },
                    "flag_mode": {
                        "description": "`draft`: queue a flag when the policy check's likelihood >= `flag_threshold`.",
                        "type": "string",
                        "default": "draft",
                        "enum": [
                            "off",
                            "draft"
                        ]
                    },
                    "flag_threshold": {
                        "type": "number",
                        "format": "float",
                        "default": 0.7,
                        "maximum": 1,
                        "minimum": 0
                    },
                    "browser_automation": {
                        "description": "Review agent v2: approved replies (reply mode `approve`) and flags on sites without an API are carried out by the grades.com browser in the account connected under `browser-sessions`, instead of being left for you to post. Premium; only while the feature is available (`GET .../browser-sessions` `meta.enabled`). Never used for auto-posts.",
                        "type": "boolean",
                        "default": false
                    },
                    "auto_post_languages": {
                        "description": "Both auto modes (`auto_positive`, `auto_all`): the languages (ISO 639-1 codes) a reply may be posted in without a person. The agent auto-posts only when the review AND the reply are in one of them; otherwise the draft waits for approval with the escalation reason `language_not_allowed` (\"Reply is in Spanish; auto-posting is limited to English\"). A review too short to tell its language (\"Great!\") passes only with English on the list, an English reply and short ASCII text. Default `[\"en\"]`; sending `null` or `[]` restores it.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es",
                                "fr",
                                "pt",
                                "de",
                                "it",
                                "vi",
                                "tl",
                                "zh",
                                "ja",
                                "ko",
                                "ru",
                                "uk",
                                "ar",
                                "he",
                                "fa",
                                "hi",
                                "el",
                                "th",
                                "pl",
                                "ht"
                            ]
                        },
                        "default": [
                            "en"
                        ]
                    },
                    "reply_language_mode": {
                        "description": "Which language reply drafts are written in (docs/review-agent.md \"Languages\"): `match_review` (default) the review's language; `always_english` English; `allowed_list` the review's language when it is one of `reply_languages`, otherwise English. Separate from `auto_post_languages`, which decides what may be posted without a person. HQ lock path `reply_language`.",
                        "type": "string",
                        "default": "match_review",
                        "enum": [
                            "match_review",
                            "always_english",
                            "allowed_list"
                        ]
                    },
                    "reply_languages": {
                        "description": "`allowed_list`: the review languages (ISO 639-1) replied to in their own language; English is always the fallback. Sending `null` or `[]` clears it.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "en",
                                "es",
                                "fr",
                                "pt",
                                "de",
                                "it",
                                "vi",
                                "tl",
                                "zh",
                                "ja",
                                "ko",
                                "ru",
                                "uk",
                                "ar",
                                "he",
                                "fa",
                                "hi",
                                "el",
                                "th",
                                "pl",
                                "ht"
                            ]
                        },
                        "default": []
                    },
                    "contact_signoff": {
                        "description": "Direct-contact sign-off: replies to negative reviews (rated 1 to 3) may invite the reviewer to get in touch using the business's phone number and / or e-mail (`contact_signoff_phone`, `contact_signoff_email`) so the issue can be handled privately. `false` (default): drafts never contain contact details. Replies to positive or unrated reviews never contain them.",
                        "type": "boolean",
                        "default": false
                    },
                    "contact_signoff_phone": {
                        "description": "With `contact_signoff` on: the line may give the company's phone number.",
                        "type": "boolean",
                        "default": true
                    },
                    "contact_signoff_email": {
                        "description": "With `contact_signoff` on: the line may give the company's e-mail address. Off by default: replies are public and an address posted in them can be collected for spam. Left out anyway when its domain is not the domain of the company website (an agency address such as `studio@agency.com` for `studio.com`; free providers like Gmail are kept).",
                        "type": "boolean",
                        "default": false
                    },
                    "include_contact_details": {
                        "description": "Deprecated, kept for older clients: the same as `contact_signoff`. Writing `true` switches the sign-off on with the phone number (the e-mail choice stays); `false` switches it off. The new fields of the same body win.",
                        "type": "boolean",
                        "deprecated": true,
                        "default": false
                    },
                    "tone": {
                        "description": "Overrides the company's AI tone for agent drafts (e.g. professional, friendly, apologetic).",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 50
                    },
                    "custom_instructions": {
                        "description": "Reply rules of the business, stated to the model as non-negotiable hard rules: the draft is checked against them and rewritten once if it breaks one (otherwise the action is flagged \"NEEDS REVIEW\" in its rationale).",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 1000
                    },
                    "report_mode": {
                        "description": "Removal reports: `off`; `draft` (the policy check drafts flags above `flag_threshold`, approved one by one); `auto` (the decision engine decides each negative review by `report_rules`, every 10 minutes; `report_rules.approval` says which reports wait for a person). Kept in step with `flag_mode`.",
                        "type": "string",
                        "default": "draft",
                        "enum": [
                            "off",
                            "draft",
                            "auto"
                        ]
                    },
                    "report_rules": {
                        "$ref": "#/components/schemas/V1AgentReportRules"
                    },
                    "reports_consent": {
                        "description": "The consent to file removal reports without a person's approval: the version accepted, when, and whether it is the current one (`meta.report_consent_version`).",
                        "properties": {
                            "version": {
                                "type": "string",
                                "nullable": true
                            },
                            "consented_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "current": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "reply_voice": {
                        "description": "How replies sound: a preset (`meta.voices`) and / or the business's own words (max 600). Style only: placed below the hard rules, it never overrides them.",
                        "properties": {
                            "preset": {
                                "type": "string",
                                "nullable": true
                            },
                            "custom": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "reply_signature": {
                        "description": "A sign-off line added under every reply draft (max 120; no links, e-mail addresses or phone numbers).",
                        "type": "string",
                        "nullable": true
                    },
                    "rules": {
                        "description": "The same settings as one rule set: `approval` {replies, reports} (all | negative_only | none), `reply` {mode, voice, signature, include_contact_details, contact_signoff {enabled, phone, email}, custom_instructions, escalation {max_rating, daily_cap, quiet_hours_start, quiet_hours_end}, language {mode: match_review | always_english | allowed_list, reply_languages, auto_post_languages}} (mode `review` is still accepted as `match_review`), `reports` {mode, ...report_rules}. Write it back (any subset) with `PUT` `rules`, reset blocks with `reset`.",
                        "type": "object"
                    },
                    "last_triaged_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1AgentReportRules": {
                "description": "Rules of removal reports in report mode `auto` (docs/review-agent.md 3.9).",
                "properties": {
                    "approval": {
                        "description": "`all`: every report waits for a person; `negative_only`: reports of reviews rated `approval_max_rating` or lower wait, the rest are filed hands-free; `none`: every report is filed hands-free. Hands-free needs Premium `removal_filing` and the consent.",
                        "type": "string",
                        "default": "all",
                        "enum": [
                            "all",
                            "negative_only",
                            "none"
                        ]
                    },
                    "max_rating": {
                        "description": "Reviews rated this or lower are checked.",
                        "type": "integer",
                        "default": 2,
                        "maximum": 4,
                        "minimum": 1
                    },
                    "approval_max_rating": {
                        "type": "integer",
                        "default": 1,
                        "maximum": 4,
                        "minimum": 0
                    },
                    "assertiveness": {
                        "description": "`strict` (\"Strict only\"): clear, unmistakable violations only (confidence >= 0.8); `assertive` (\"Standard\"): only when the review clearly breaks a named rule (confidence >= 0.8).",
                        "type": "string",
                        "default": "assertive",
                        "enum": [
                            "strict",
                            "assertive"
                        ]
                    },
                    "allowed_grounds": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "not_a_customer",
                                "competitor",
                                "conflict_of_interest",
                                "fake",
                                "off_topic",
                                "harassment",
                                "pii",
                                "spam",
                                "duplicate"
                            ]
                        }
                    },
                    "sites": {
                        "description": "Review sites to report on; null = every site.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "nullable": true
                    },
                    "daily_cap": {
                        "type": "integer",
                        "default": 10,
                        "maximum": 50,
                        "minimum": 1
                    },
                    "ask_for_login": {
                        "description": "When a site only takes the report from the business's own account, ask the business to connect it (else the report is prepared for the business to file).",
                        "type": "boolean",
                        "default": true
                    },
                    "instructions": {
                        "description": "The business's own report instructions (they can narrow what is reported, never widen it).",
                        "type": "string",
                        "nullable": true,
                        "maxLength": 1000
                    }
                },
                "type": "object"
            },
            "V1AiProbe": {
                "description": "One AI engine's answer to one perception prompt.",
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "run_id": {
                        "description": "The probe run (radar scan) uuid.",
                        "type": "string",
                        "format": "uuid"
                    },
                    "engine": {
                        "type": "string",
                        "enum": [
                            "gemini",
                            "openai",
                            "perplexity",
                            "anthropic"
                        ]
                    },
                    "engine_label": {
                        "description": "The name of the assistant to show: ChatGPT, Perplexity, Gemini or Claude (never the model; see `model`).",
                        "type": "string",
                        "example": "Claude"
                    },
                    "prompt_template": {
                        "type": "string",
                        "enum": [
                            "customer_reviews",
                            "well_reviewed",
                            "ratings"
                        ]
                    },
                    "prompt": {
                        "type": "string"
                    },
                    "answer": {
                        "type": "string",
                        "nullable": true
                    },
                    "sentiment": {
                        "type": "string",
                        "enum": [
                            "positive",
                            "mixed",
                            "negative",
                            "unknown"
                        ]
                    },
                    "sentiment_score": {
                        "description": "-1 to 1",
                        "type": "number",
                        "format": "float",
                        "nullable": true
                    },
                    "summary": {
                        "type": "string",
                        "nullable": true
                    },
                    "rating_claim": {
                        "type": "string",
                        "example": "4.8 on Google (212 reviews)",
                        "nullable": true
                    },
                    "rating_quotes": {
                        "description": "Each rating / review count the answer quotes, checked against what grades.com had for that site when the probe ran (null = not checked yet). Verdict: `accurate` (rating within 0.1 star, count within 10%), `stale` (fewer reviews than the site has: an older snapshot), `wrong`, `unknown_site` (no site named or no data for it). `basis`: `platform` (the site's own figures) or `stored_reviews` (reviews grades.com stored; a floor, so a higher quoted count is not judged).",
                        "type": "array",
                        "items": {
                            "properties": {
                                "site": {
                                    "type": "string",
                                    "example": "google",
                                    "nullable": true
                                },
                                "quoted_rating": {
                                    "type": "number",
                                    "format": "float",
                                    "nullable": true
                                },
                                "quoted_count": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "actual_rating": {
                                    "type": "number",
                                    "format": "float",
                                    "nullable": true
                                },
                                "actual_count": {
                                    "type": "integer",
                                    "nullable": true
                                },
                                "rating_delta": {
                                    "description": "quoted - actual",
                                    "type": "number",
                                    "format": "float",
                                    "nullable": true
                                },
                                "count_delta_pct": {
                                    "type": "number",
                                    "format": "float",
                                    "nullable": true
                                },
                                "verdict": {
                                    "type": "string",
                                    "enum": [
                                        "accurate",
                                        "stale",
                                        "wrong",
                                        "unknown_site",
                                        "about_sibling_location"
                                    ]
                                },
                                "basis": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                        "platform",
                                        "stored_reviews"
                                    ]
                                },
                                "observed_at": {
                                    "type": "string",
                                    "format": "date-time",
                                    "nullable": true
                                }
                            },
                            "type": "object"
                        },
                        "nullable": true
                    },
                    "mentioned": {
                        "description": "Whether the answer is about the business (`yes`), says it knows nothing about it (`no`) or describes a different business (`wrong_entity`); null = not judged yet.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "yes",
                            "no",
                            "wrong_entity"
                        ]
                    },
                    "mentioned_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "negative_claims": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "business_facts": {
                        "description": "Facts about the business the answer states (\"not accredited by the BBB\", \"does not list prices on its website\"): never complaints, never alerts. `topic`: a BusinessFacts topic or `other`; `text`: the answer's own sentence (clinical terms scrubbed for healthcare businesses). Empty on answers stored before 2026-12-19.",
                        "type": "array",
                        "items": {
                            "properties": {
                                "topic": {
                                    "type": "string",
                                    "example": "bbb_not_accredited"
                                },
                                "label": {
                                    "type": "string",
                                    "example": "Not accredited by the BBB"
                                },
                                "text": {
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "cited_urls": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "url": {
                                    "type": "string"
                                },
                                "domain": {
                                    "type": "string"
                                },
                                "title": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "review_site": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "tracked": {
                                    "type": "boolean"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "mentioned_sites": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "model": {
                        "type": "string",
                        "nullable": true
                    },
                    "input_tokens": {
                        "type": "integer",
                        "nullable": true
                    },
                    "output_tokens": {
                        "type": "integer",
                        "nullable": true
                    },
                    "cost_usd": {
                        "type": "number",
                        "format": "float",
                        "nullable": true
                    },
                    "error": {
                        "description": "Why the assistant gave no answer, as a plain sentence (never the provider's own message); null when it answered.",
                        "type": "string",
                        "nullable": true
                    },
                    "error_code": {
                        "description": "The reason as a code; null when it answered.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "engine_busy",
                            "engine_timeout",
                            "engine_unavailable",
                            "engine_declined",
                            "engine_error"
                        ]
                    },
                    "run_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                },
                "type": "object"
            },
            "V1BrowserConnectAttempt": {
                "description": "A connect attempt of a review-site account (review agent v2) in API v1. Never includes the token.",
                "required": [
                    "uuid",
                    "method",
                    "status",
                    "expires_at",
                    "deadline_at",
                    "error_code",
                    "error_message",
                    "created_at",
                    "finished_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "method": {
                        "description": "`live` (the owner signs in on the live sign-in page) or `credentials` (sign-in details shared, encrypted in the browser to the worker).",
                        "type": "string",
                        "enum": [
                            "live",
                            "credentials"
                        ]
                    },
                    "status": {
                        "description": "`pending` (link not opened yet), `in_progress`, `needs_code` (waiting for a verification code), `succeeded`, `failed`, `expired`, `canceled`.",
                        "type": "string",
                        "enum": [
                            "pending",
                            "in_progress",
                            "needs_code",
                            "succeeded",
                            "failed",
                            "expired",
                            "canceled"
                        ]
                    },
                    "expires_at": {
                        "description": "The one-time link must be opened before this.",
                        "type": "string",
                        "format": "date-time"
                    },
                    "deadline_at": {
                        "description": "Set when the worker opened the attempt: sign-in must finish before this.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "error_code": {
                        "description": "Why it ended: `captcha`, `invalid_credentials`, `two_factor_failed`, `login_timeout`, `abandoned`, `canceled`, `superseded`, `disconnected`, `link_expired`, `timed_out`, `method_mismatch`, `site_error`, `network`, `credentials_unreadable`, `internal`.",
                        "type": "string",
                        "nullable": true
                    },
                    "error_message": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "finished_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1BrowserSession": {
                "description": "A connected review-site account (review agent v2) in API v1: a company's own login (`scope` company) or a\nGrades-owned reporter account (`scope` platform, only in the super admin list). Never includes the sealed\nsession, the user agent or the proxy.",
                "required": [
                    "uuid",
                    "scope",
                    "site",
                    "site_label",
                    "status",
                    "account_label",
                    "consent_version",
                    "consented_at",
                    "connected_at",
                    "last_login_check_at",
                    "last_login_ok_at",
                    "last_error",
                    "revoked_at",
                    "created_at",
                    "state",
                    "connect"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "scope": {
                        "description": "`company`: a business login of the company; `platform`: a Grades-owned reporter account.",
                        "type": "string",
                        "enum": [
                            "company",
                            "platform"
                        ]
                    },
                    "site": {
                        "type": "string",
                        "example": "yelp"
                    },
                    "site_label": {
                        "type": "string",
                        "example": "Yelp for Business"
                    },
                    "status": {
                        "description": "`pending_connect` (waiting for the owner to sign in), `active`, `expired` (signed out: reconnect), `revoked` (disconnected).",
                        "type": "string",
                        "enum": [
                            "pending_connect",
                            "active",
                            "expired",
                            "revoked"
                        ]
                    },
                    "account_label": {
                        "type": "string",
                        "nullable": true
                    },
                    "consent_version": {
                        "type": "string"
                    },
                    "consented_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "connected_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_login_check_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_login_ok_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_error": {
                        "description": "Why the last check or job needed the owner: `login_required`, `captcha`, `two_factor`.",
                        "type": "string",
                        "nullable": true
                    },
                    "revoked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "state": {
                        "description": "What the dashboard shows: `connected`, `locked` (active, but the site asked for a CAPTCHA or a verification code during a job: sign in again), `needs_relogin` (expired), `pending` (not connected yet), `disconnected`.",
                        "type": "string",
                        "enum": [
                            "connected",
                            "locked",
                            "needs_relogin",
                            "pending",
                            "disconnected"
                        ]
                    },
                    "connect": {
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/V1BrowserConnectAttempt"
                            },
                            {
                                "type": "object",
                                "nullable": true,
                                "enum": [
                                    null
                                ]
                            }
                        ],
                        "description": "The latest connect attempt, or null."
                    }
                },
                "type": "object"
            },
            "V1Company": {
                "description": "A company (location) in API v1.",
                "required": [
                    "uuid",
                    "name",
                    "location_nickname",
                    "slug",
                    "website",
                    "phone",
                    "email",
                    "address",
                    "timezone",
                    "role",
                    "hq_company",
                    "agency",
                    "locations_count",
                    "auto_connect_sources",
                    "access",
                    "created_at"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string",
                        "example": "Acme Dental"
                    },
                    "location_nickname": {
                        "type": "string",
                        "example": "Northside Office",
                        "nullable": true
                    },
                    "slug": {
                        "type": "string",
                        "example": "acme-dental"
                    },
                    "website": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "phone": {
                        "type": "string",
                        "example": "+12125550100",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "nullable": true
                    },
                    "address": {
                        "properties": {
                            "line1": {
                                "type": "string",
                                "nullable": true
                            },
                            "line2": {
                                "type": "string",
                                "nullable": true
                            },
                            "unit": {
                                "type": "string",
                                "nullable": true
                            },
                            "city": {
                                "type": "string",
                                "nullable": true
                            },
                            "state": {
                                "type": "string",
                                "nullable": true
                            },
                            "zip": {
                                "type": "string",
                                "nullable": true
                            },
                            "country": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "timezone": {
                        "type": "string",
                        "example": "America/New_York",
                        "nullable": true
                    },
                    "role": {
                        "description": "The caller's role in this company (`super_admin` for platform super admins).",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "owner",
                            "super_admin",
                            "admin",
                            "approver",
                            "reviewer",
                            "viewer",
                            "user"
                        ]
                    },
                    "hq_company": {
                        "description": "The HQ this location belongs to (billed as an extra location of its business), or null.",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "agency": {
                        "description": "The agency this business is a client of (directly, or through its HQ; docs/agencies.md), or null.",
                        "properties": {
                            "uuid": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "slug": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "locations_count": {
                        "description": "Locations attached to this company as their HQ (0 for a location).",
                        "type": "integer"
                    },
                    "access": {
                        "description": "How the caller reaches this company (docs/multi-location.md): `via` = `member` (own membership), `hq` (an all-locations membership of its HQ), `agency` (an all-clients agency membership) or `superadmin`; `all_locations` = your own membership covers all locations of this HQ; `group_access` = the HQ views (`/v1/companies/{uuid}/locations/...`) are open to the caller. Null when unknown.",
                        "properties": {
                            "via": {
                                "type": "string",
                                "enum": [
                                    "member",
                                    "hq",
                                    "agency",
                                    "superadmin"
                                ]
                            },
                            "all_locations": {
                                "type": "boolean"
                            },
                            "group_access": {
                                "type": "boolean"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "auto_connect_sources": {
                        "description": "The review radar and source discovery connect profiles they find on verified customer-review sites by themselves (docs/review-radar.md \"Auto-connect\"). Off by default.",
                        "type": "boolean"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewFlag": {
                "required": [
                    "id",
                    "uuid",
                    "review_uuid",
                    "source",
                    "reason",
                    "details",
                    "evidence_urls",
                    "status",
                    "resolution",
                    "external_reference",
                    "notes",
                    "submitted_at",
                    "resolved_at",
                    "created_at",
                    "updated_at",
                    "next_steps",
                    "report"
                ],
                "properties": {
                    "id": {
                        "description": "Numeric id; `{flag}` paths accept it or the uuid.",
                        "type": "integer"
                    },
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "review_uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "source": {
                        "description": "The collector that stored the review: an internal id (`yelp_apify`, `google_maps`, `api`, ...) that may change. Show and filter by `site`.",
                        "type": "string",
                        "example": "google"
                    },
                    "site": {
                        "description": "The review platform (`google`, `yelp`, `direct`, ...), as on V1Review.",
                        "type": "string",
                        "example": "google"
                    },
                    "source_name": {
                        "description": "Display name of the platform.",
                        "type": "string",
                        "example": "Google"
                    },
                    "reason": {
                        "type": "string",
                        "enum": [
                            "not_a_customer",
                            "competitor",
                            "spam",
                            "off_topic",
                            "harassment",
                            "pii",
                            "conflict_of_interest",
                            "duplicate",
                            "fake",
                            "policy_other"
                        ]
                    },
                    "details": {
                        "type": "string",
                        "nullable": true
                    },
                    "evidence_urls": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "url"
                        },
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "open",
                            "submitted",
                            "resolved",
                            "rejected",
                            "withdrawn"
                        ]
                    },
                    "resolution": {
                        "description": "How a resolved flag ended: `removed_by_platform` when Grades saw the review disappear from its site (the flag goes back to `submitted` if the review comes back).",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "removed_by_platform"
                        ]
                    },
                    "external_reference": {
                        "description": "The review site's case or ticket id.",
                        "type": "string",
                        "nullable": true
                    },
                    "notes": {
                        "type": "string",
                        "nullable": true
                    },
                    "submitted_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "resolved_at": {
                        "description": "When the flag was resolved, rejected or withdrawn.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "next_steps": {
                        "description": "How to report the review on its site. Grades does not report it itself.",
                        "properties": {
                            "site": {
                                "type": "string",
                                "example": "google"
                            },
                            "report_url": {
                                "type": "string",
                                "format": "url",
                                "nullable": true
                            },
                            "owner_portal_url": {
                                "type": "string",
                                "format": "url",
                                "nullable": true
                            },
                            "guideline_url": {
                                "type": "string",
                                "format": "url",
                                "nullable": true
                            },
                            "steps": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "what_works": {
                                "description": "Only when enough reports were filed across Grades.com: the reasons whose reports got reviews removed on this site, best first (counts only).",
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "reason": {
                                            "type": "string"
                                        },
                                        "rate": {
                                            "type": "number"
                                        },
                                        "removed": {
                                            "type": "integer"
                                        },
                                        "reports": {
                                            "type": "integer"
                                        },
                                        "median_lag_days": {
                                            "type": "integer",
                                            "nullable": true
                                        },
                                        "note": {
                                            "type": "string"
                                        }
                                    },
                                    "type": "object"
                                }
                            }
                        },
                        "type": "object"
                    },
                    "handling": {
                        "$ref": "#/components/schemas/V1ReviewHandling"
                    },
                    "report": {
                        "$ref": "#/components/schemas/V1ReportOutcome"
                    }
                },
                "type": "object"
            },
            "V1ReportOutcome": {
                "description": "What came of the removal report (docs/review-agent.md \"Constantly improving\").",
                "properties": {
                    "filed": {
                        "type": "boolean"
                    },
                    "filed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "filed_via": {
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "manual",
                            "browser",
                            "api"
                        ]
                    },
                    "result": {
                        "description": "`pending` until the review is removed (`removed`), still live 30 days after filing (`still_live`), back after a removal (`restored`), or the report was withdrawn.",
                        "type": "string",
                        "enum": [
                            "pending",
                            "removed",
                            "still_live",
                            "restored",
                            "withdrawn"
                        ]
                    },
                    "result_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "lag_days": {
                        "description": "Days from filing to removal.",
                        "type": "integer",
                        "nullable": true
                    },
                    "success_note": {
                        "description": "How reports with this reason fared on this site across Grades.com, when enough were filed.",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1Reply": {
                "description": "The result of POST /v1/companies/{company}/reviews/{review}/reply.",
                "required": [
                    "review_uuid",
                    "text",
                    "status",
                    "pushed_to_source",
                    "source",
                    "synced_at",
                    "manual_url",
                    "push_error"
                ],
                "properties": {
                    "review_uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "review": {
                        "description": "The same uuid as `review_uuid` (the field the Zapier and Make reply steps map).",
                        "type": "string",
                        "format": "uuid"
                    },
                    "text": {
                        "type": "string"
                    },
                    "status": {
                        "description": "`published`: the review site accepted the reply; `saved`: stored in Grades only.",
                        "type": "string",
                        "enum": [
                            "published",
                            "saved"
                        ]
                    },
                    "pushed_to_source": {
                        "type": "boolean"
                    },
                    "source": {
                        "description": "The collector that stored the review: an internal id (`yelp_apify`, `google_maps`, `api`, ...) that may change. Show and filter by `site`.",
                        "type": "string",
                        "example": "yelp"
                    },
                    "site": {
                        "description": "The review platform (`google`, `yelp`, `direct`, ...), as on V1Review.",
                        "type": "string",
                        "example": "yelp"
                    },
                    "source_name": {
                        "description": "Display name of the platform.",
                        "type": "string",
                        "example": "Yelp"
                    },
                    "synced_at": {
                        "description": "When the review site accepted the reply.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "manual_url": {
                        "description": "When not pushed: the review on its site, where the owner can paste the reply.",
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "push_error": {
                        "description": "When the push to the review site failed: its HTTP status (null if unreachable) and message.",
                        "properties": {
                            "status": {
                                "type": "integer",
                                "nullable": true
                            },
                            "message": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "handling": {
                        "$ref": "#/components/schemas/V1ReviewHandling"
                    }
                },
                "type": "object"
            },
            "V1ReviewMention": {
                "description": "A page about a company found by the review radar.",
                "required": [
                    "id",
                    "engine",
                    "query",
                    "url",
                    "domain",
                    "title",
                    "snippet",
                    "position",
                    "driver_match",
                    "is_review_page",
                    "tracked",
                    "own_site",
                    "review_excerpt",
                    "rating_hint",
                    "review_count_hint",
                    "relevance",
                    "relevance_reasons",
                    "status",
                    "dismiss_reason",
                    "seen_count",
                    "first_seen_at",
                    "last_seen_at",
                    "also_found_by",
                    "more_pages"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "engine": {
                        "type": "string",
                        "enum": [
                            "google_web",
                            "google_ai_overview",
                            "bing_web",
                            "chatgpt",
                            "ai_gemini",
                            "ai_openai",
                            "ai_perplexity",
                            "ai_anthropic"
                        ]
                    },
                    "query": {
                        "description": "The search query or AI prompt key that found it.",
                        "type": "string"
                    },
                    "url": {
                        "type": "string",
                        "format": "url"
                    },
                    "domain": {
                        "type": "string",
                        "example": "yelp.com"
                    },
                    "title": {
                        "type": "string",
                        "nullable": true
                    },
                    "snippet": {
                        "type": "string",
                        "nullable": true
                    },
                    "position": {
                        "type": "integer",
                        "nullable": true
                    },
                    "driver_match": {
                        "description": "The review site it belongs to (a source driver such as `yelp`, or another review site such as `vitals`).",
                        "type": "string",
                        "nullable": true
                    },
                    "is_review_page": {
                        "type": "boolean"
                    },
                    "tracked": {
                        "description": "Its review site is connected as a source of the company.",
                        "type": "boolean"
                    },
                    "own_site": {
                        "description": "On the company's own website.",
                        "type": "boolean"
                    },
                    "review_excerpt": {
                        "type": "string",
                        "nullable": true
                    },
                    "rating_hint": {
                        "type": "number",
                        "format": "float",
                        "nullable": true
                    },
                    "review_count_hint": {
                        "type": "integer",
                        "nullable": true
                    },
                    "relevance": {
                        "description": "How sure the radar is that the page is about this business (0-1; below `RADAR_MIN_RELEVANCE`, default 0.35, it is dismissed as `low_relevance`). See docs/review-radar.md \"Relevance\".",
                        "type": "number",
                        "format": "float",
                        "example": 0.85
                    },
                    "relevance_reasons": {
                        "description": "Why: `own_site`, `name_exact`, `name_words`, `name_variant`, `name_partial`, `name_missing`, `city`, `family_city`, `metro`, `state`, `family_state`, `country`, `other_state`, `foreign_place`, `foreign_directory`, `foreign_tld`, `tripadvisor_elsewhere`, `spam_host`. Empty for mentions stored before scoring and not re-scored yet.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "new",
                            "seen",
                            "dismissed"
                        ]
                    },
                    "dismiss_reason": {
                        "description": "Why it is dismissed: `low_relevance` (by the radar; restored when it scores higher later), `search_page` (a search-result or category page listing many businesses), `user`, or `duplicate_of:<id>` (another variant of the same page, www / m / http, a trailing slash, a fragment or tracking parameters, which the engine already found as mention `<id>`; kept for history, hidden from the list).",
                        "type": "string",
                        "example": "duplicate_of:87998",
                        "nullable": true
                    },
                    "seen_count": {
                        "type": "integer"
                    },
                    "first_seen_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "last_seen_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "also_found_by": {
                        "description": "Other engines that found the same page (rows folded into this one in the list; the list shows one row per page). Only set in the list.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "google_web",
                                "google_ai_overview",
                                "bing_web",
                                "chatgpt",
                                "ai_gemini",
                                "ai_openai",
                                "ai_perplexity",
                                "ai_anthropic"
                            ]
                        }
                    },
                    "more_pages": {
                        "description": "Other pages of the same site under the same title folded into this one in the list (a BBB profile and its complaints page). 0 for a plain page. Only set in the list.",
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "V1ReviewPageLink": {
                "required": [
                    "id",
                    "type",
                    "label",
                    "enabled",
                    "available"
                ],
                "properties": {
                    "id": {
                        "description": "Stable link id (ULID).",
                        "type": "string"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "source",
                            "custom"
                        ]
                    },
                    "source_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "driver": {
                        "type": "string",
                        "example": "google",
                        "nullable": true
                    },
                    "label": {
                        "type": "string",
                        "example": "Google"
                    },
                    "url": {
                        "description": "The URL the button opens (null: unknown).",
                        "type": "string",
                        "nullable": true
                    },
                    "auto_url": {
                        "description": "Source links: the URL derived from the source (Google: the \"write a review\" URL when the place id is known).",
                        "type": "string",
                        "nullable": true
                    },
                    "url_override": {
                        "description": "Stored URL (source override, or the custom URL).",
                        "type": "string",
                        "nullable": true
                    },
                    "enabled": {
                        "type": "boolean"
                    },
                    "available": {
                        "description": "false: the source was removed or no URL is known; the button is not shown.",
                        "type": "boolean"
                    },
                    "policy": {
                        "description": "`no_solicit` (Yelp forbids asking for reviews), `employer_reviews` (Glassdoor, Indeed), null = may be asked.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "no_solicit",
                            "employer_reviews"
                        ]
                    },
                    "weight": {
                        "description": "Suggested weight (0-100) of the site of the link; null: unknown site.",
                        "type": "integer",
                        "nullable": true
                    },
                    "link_site": {
                        "description": "Custom links to a link-only review site (Cars.com, Nextdoor, ...): the site. Review link only: Grades.com does not collect, monitor, reply to or dispute reviews there. null for every other link.",
                        "properties": {
                            "key": {
                                "type": "string",
                                "example": "cars_com"
                            },
                            "label": {
                                "type": "string",
                                "example": "Cars.com"
                            },
                            "category": {
                                "type": "string",
                                "example": "auto"
                            },
                            "review_link_only": {
                                "type": "boolean",
                                "example": true
                            },
                            "in_app_only": {
                                "description": "true: the site takes reviews only from its own bookings or orders.",
                                "type": "boolean"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "direct_target": {
                        "description": "Whether this link can be the page's destination (`destination_link_id`), and why not.",
                        "properties": {
                            "allowed": {
                                "type": "boolean"
                            },
                            "reason": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "disabled",
                                    "unavailable",
                                    "no_solicit",
                                    "employer_reviews",
                                    "site_rules",
                                    "in_app_only",
                                    "not_a_review_site"
                                ]
                            },
                            "message": {
                                "description": "What to tell the owner.",
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewPageDestination": {
                "description": "Where the page sends visitors (docs/review-pages.md \"Destination\").",
                "properties": {
                    "to": {
                        "description": "`page` (the review page) or `site` (straight to one button's site).",
                        "type": "string",
                        "enum": [
                            "page",
                            "site"
                        ]
                    },
                    "link_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "site": {
                        "description": "The site's name.",
                        "type": "string",
                        "example": "Google",
                        "nullable": true
                    },
                    "url": {
                        "description": "Where the redirect goes.",
                        "type": "string",
                        "nullable": true
                    },
                    "line": {
                        "description": "The counter screen's and the app's line.",
                        "type": "string",
                        "example": "Scan to review us on Google"
                    },
                    "notice": {
                        "description": "Set when the chosen button no longer qualifies (switched off, no address): visitors see the page.",
                        "type": "string",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewLinkSite": {
                "description": "A link-only review site (config review_link_sites): a button only, nothing collected or monitored.",
                "properties": {
                    "key": {
                        "type": "string",
                        "example": "cars_com"
                    },
                    "label": {
                        "type": "string",
                        "example": "Cars.com"
                    },
                    "category": {
                        "type": "string",
                        "example": "auto"
                    },
                    "icon": {
                        "type": "string",
                        "nullable": true
                    },
                    "hosts": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "review_link_only": {
                        "type": "boolean",
                        "example": true
                    },
                    "in_app_only": {
                        "type": "boolean"
                    },
                    "has_review_form_link": {
                        "description": "true: the button opens the site's write-a-review form.",
                        "type": "boolean"
                    },
                    "pattern_verified": {
                        "type": "boolean"
                    },
                    "example": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1ReviewPageWarning": {
                "required": [
                    "code",
                    "link_id",
                    "message"
                ],
                "properties": {
                    "code": {
                        "type": "string",
                        "enum": [
                            "yelp_no_solicit"
                        ]
                    },
                    "link_id": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "V1ReviewPage": {
                "required": [
                    "id",
                    "name",
                    "slug",
                    "is_default",
                    "enabled",
                    "url",
                    "qr_url",
                    "counter_url",
                    "links",
                    "available_sources"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string",
                        "example": "Main page"
                    },
                    "slug": {
                        "description": "Unique within the company.",
                        "type": "string",
                        "example": "main"
                    },
                    "is_default": {
                        "type": "boolean"
                    },
                    "enabled": {
                        "description": "Off: the public URL answers 404.",
                        "type": "boolean"
                    },
                    "headline": {
                        "description": "Stored headline; null = the default (`appearance.headline`).",
                        "type": "string",
                        "nullable": true
                    },
                    "intro": {
                        "description": "Stored intro; null = the default (`appearance.intro`).",
                        "type": "string",
                        "nullable": true
                    },
                    "closing": {
                        "description": "Closing line under the buttons; null = none.",
                        "type": "string",
                        "nullable": true
                    },
                    "display_name": {
                        "description": "Business name override; null = the company name.",
                        "type": "string",
                        "nullable": true
                    },
                    "accent_color": {
                        "description": "Stored accent; null = the default.",
                        "type": "string",
                        "example": "#4f46e5",
                        "nullable": true
                    },
                    "theme": {
                        "description": "light or dark; null = light.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "light",
                            "dark"
                        ]
                    },
                    "show_logo": {
                        "description": "Stored logo switch; null = shown.",
                        "type": "boolean",
                        "nullable": true
                    },
                    "text_needs_review": {
                        "description": "true: page text the compliance check could not read (not English or Spanish); see appearance.text_check.",
                        "type": "boolean"
                    },
                    "show_feedback_form": {
                        "type": "boolean"
                    },
                    "feedback_email": {
                        "type": "string",
                        "nullable": true
                    },
                    "business_name": {
                        "description": "The name the page shows (display_name, else the company name).",
                        "type": "string"
                    },
                    "company_name": {
                        "description": "The company name.",
                        "type": "string"
                    },
                    "logo_url": {
                        "description": "The company logo (uploaded in the dashboard: Company Settings > Branding, or the review page editor); null when there is none. Shown on the page unless show_logo is false.",
                        "type": "string",
                        "nullable": true
                    },
                    "appearance": {
                        "$ref": "#/components/schemas/V1ReviewPageAppearance"
                    },
                    "url": {
                        "description": "Public URL: /r/<company-slug> for the default page, /r/<company-slug>/<page-slug> otherwise.",
                        "type": "string",
                        "example": "https://app.grades.com/r/studio-esthetique"
                    },
                    "qr_url": {
                        "type": "string",
                        "example": "https://app.grades.com/r/studio-esthetique/qr.svg"
                    },
                    "counter_url": {
                        "description": "Counter screen: a full-screen QR code of the page to show on a phone or tablet (login-free, noindex). Its QR code opens the page with ?src=counter, recorded as such in the page views.",
                        "type": "string",
                        "example": "https://app.grades.com/r/studio-esthetique/counter"
                    },
                    "android_app_url": {
                        "description": "Opens the counter screen in the Grades.com Android app (falls back to the screen in a browser). null while the app is not public (ANDROID_APP_LINK_ENABLED off). Show it on Android devices only.",
                        "type": "string",
                        "example": null,
                        "nullable": true
                    },
                    "visits": {
                        "description": "Visitors of the page over the last `days` days (one per visitor and day; crawlers not counted), by where they came from: `direct` (the link, a QR code printed before `src=qr`, anything without a marker), `qr` (the page's QR code), `counter` (the counter screen's QR code), `app-qr` and `app-tap` (the Grades.com Android app). The marker is the page URL's `src` parameter.",
                        "properties": {
                            "days": {
                                "type": "integer",
                                "example": 30
                            },
                            "total": {
                                "type": "integer",
                                "example": 12
                            },
                            "by_source": {
                                "properties": {
                                    "direct": {
                                        "type": "integer",
                                        "example": 9
                                    },
                                    "counter": {
                                        "type": "integer",
                                        "example": 3
                                    },
                                    "app-qr": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "app-tap": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "qr": {
                                        "description": "Scans of the page's own QR code (qr.svg encodes ?src=qr).",
                                        "type": "integer",
                                        "example": 0
                                    }
                                },
                                "type": "object"
                            }
                        },
                        "type": "object"
                    },
                    "links": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewPageLink"
                        }
                    },
                    "available_sources": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "source_id": {
                                    "type": "integer"
                                },
                                "driver": {
                                    "type": "string"
                                },
                                "display_name": {
                                    "type": "string"
                                },
                                "url": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "on_page": {
                                    "type": "boolean"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "mode": {
                        "description": "`suggested`: the links follow the AI-suggested order (new pages); `manual`: the owner order.",
                        "type": "string",
                        "enum": [
                            "manual",
                            "suggested"
                        ]
                    },
                    "rotation": {
                        "description": "`top1` (suggested mode): each visitor sees one of the top sites first.",
                        "type": "string",
                        "enum": [
                            "off",
                            "top1"
                        ]
                    },
                    "suggested_order": {
                        "description": "Ids of the shown links in the suggested order (policy sites excluded), whatever the mode.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "also_links": {
                        "description": "Ids of shown links of policy sites (Yelp): suggested mode lists them under \"You can also find us on\".",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "warnings": {
                        "description": "Manual mode: one warning per enabled Yelp link.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewPageWarning"
                        }
                    },
                    "destination_link_id": {
                        "description": "Stored destination: null = the page, else a link id.",
                        "type": "string",
                        "nullable": true
                    },
                    "destination": {
                        "$ref": "#/components/schemas/V1ReviewPageDestination"
                    },
                    "link_sites": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewLinkSite"
                        }
                    },
                    "feedback_count": {
                        "type": "integer"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewPageAppearance": {
                "description": "What the public page shows: the effective texts and colors (docs/review-pages.md \"Look and text\").",
                "properties": {
                    "business_name": {
                        "type": "string"
                    },
                    "headline": {
                        "type": "string"
                    },
                    "intro": {
                        "type": "string"
                    },
                    "closing": {
                        "type": "string",
                        "nullable": true
                    },
                    "theme": {
                        "type": "string",
                        "enum": [
                            "light",
                            "dark"
                        ]
                    },
                    "accent_color": {
                        "description": "The accent the page uses (after the contrast check).",
                        "type": "string"
                    },
                    "accent_requested": {
                        "description": "The stored accent; null = default.",
                        "type": "string",
                        "nullable": true
                    },
                    "accent_adjusted": {
                        "description": "true: the chosen accent was too hard to read on this page, so a darker or lighter shade is used.",
                        "type": "boolean"
                    },
                    "on_accent_color": {
                        "description": "Text color on the accent (white or near-black).",
                        "type": "string"
                    },
                    "contrast": {
                        "properties": {
                            "accent_on_card": {
                                "description": "At least 3 (WCAG 1.4.11).",
                                "type": "number"
                            },
                            "text_on_accent": {
                                "description": "At least 4.5 (WCAG 1.4.3).",
                                "type": "number"
                            }
                        },
                        "type": "object"
                    },
                    "show_logo": {
                        "description": "Whether a logo is shown (switch on and a logo uploaded).",
                        "type": "boolean"
                    },
                    "logo_url": {
                        "description": "The logo shown; null = none.",
                        "type": "string",
                        "nullable": true
                    },
                    "powered_by": {
                        "description": "The page footer, always shown.",
                        "type": "string"
                    },
                    "notice": {
                        "description": "Set when the accent was adjusted: what to tell the user.",
                        "type": "string",
                        "nullable": true
                    },
                    "defaults": {
                        "description": "The default headline, intro and accent.",
                        "properties": {
                            "headline": {
                                "type": "string"
                            },
                            "intro": {
                                "type": "string"
                            },
                            "accent_color": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "text_check": {
                        "description": "needs_review: true when the headline, intro or closing is in a language the compliance check cannot read (it checks English and Spanish); notice: what to tell the owner.",
                        "properties": {
                            "needs_review": {
                                "type": "boolean"
                            },
                            "notice": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestContact": {
                "description": "A review request contact (`contact()`). `requests` (its last 10 requests) only on GET one contact.",
                "required": [
                    "id",
                    "email",
                    "phone",
                    "tags",
                    "opted_out",
                    "opt_out",
                    "can_email",
                    "can_sms"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string",
                        "nullable": true
                    },
                    "first_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "last_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "email": {
                        "type": "string",
                        "nullable": true
                    },
                    "email_quality": {
                        "description": "A role (info@) or disposable address: a warning, never a block; null = looks like a person.",
                        "properties": {
                            "code": {
                                "type": "string",
                                "enum": [
                                    "role_address",
                                    "disposable_address"
                                ]
                            },
                            "detail": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "phone": {
                        "type": "string",
                        "nullable": true
                    },
                    "tags": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "timezone": {
                        "type": "string",
                        "nullable": true
                    },
                    "external_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "source": {
                        "type": "string"
                    },
                    "email_consent": {
                        "properties": {
                            "source": {
                                "type": "string"
                            },
                            "at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "sms_consent": {
                        "description": "The SMS consent record; null without a full one.",
                        "properties": {
                            "text": {
                                "type": "string"
                            },
                            "source": {
                                "type": "string"
                            },
                            "at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "ip_recorded": {
                                "type": "boolean"
                            },
                            "version": {
                                "description": "Version of the standard wording (null: other words).",
                                "type": "string",
                                "nullable": true
                            },
                            "page_url": {
                                "description": "The Grades.com opt-in page it was given on (null: recorded elsewhere).",
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "email_status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "bounced",
                            "complained"
                        ]
                    },
                    "opted_out": {
                        "description": "Whether each channel is opted out.",
                        "properties": {
                            "email": {
                                "type": "boolean"
                            },
                            "sms": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "opt_out": {
                        "description": "Why each channel is opted out and whether an admin may undo it (null = not opted out).",
                        "properties": {
                            "email": {
                                "$ref": "#/components/schemas/V1ReviewRequestOptOutState"
                            },
                            "sms": {
                                "$ref": "#/components/schemas/V1ReviewRequestOptOutState"
                            }
                        },
                        "type": "object"
                    },
                    "suppressed": {
                        "description": "A platform-wide suppression of the email address (complaint or hard bounce); null = none.",
                        "properties": {
                            "channel": {
                                "type": "string"
                            },
                            "reason": {
                                "type": "string"
                            },
                            "at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "note": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "resubscribe_link": {
                        "description": "The one re-subscribe link of the contact: `available` = one may be sent now.",
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "sent_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "expires_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "confirmed_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    },
                    "can_email": {
                        "type": "boolean"
                    },
                    "can_sms": {
                        "type": "boolean"
                    },
                    "last_requested_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "requests": {
                        "description": "GET one contact only: its last 10 requests, newest first.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewRequest"
                        }
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestOptOutState": {
                "description": "The active opt-out of one channel of a contact.",
                "required": [
                    "reason",
                    "at",
                    "final",
                    "admin_can_reverse"
                ],
                "properties": {
                    "reason": {
                        "type": "string"
                    },
                    "at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "final": {
                        "description": "Spam complaint or STOP: only the customer can undo it.",
                        "type": "boolean"
                    },
                    "admin_can_reverse": {
                        "type": "boolean"
                    }
                },
                "type": "object",
                "nullable": true
            },
            "V1ReviewRequestResubscribeLink": {
                "description": "A re-subscribe link mailed to a contact.",
                "required": [
                    "channel",
                    "address",
                    "sent_at",
                    "expires_at",
                    "confirmed_at"
                ],
                "properties": {
                    "channel": {
                        "type": "string"
                    },
                    "address": {
                        "type": "string"
                    },
                    "sent_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "confirmed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestCampaign": {
                "description": "A review request campaign (`campaign()`).",
                "required": [
                    "id",
                    "name",
                    "status",
                    "is_default",
                    "channels",
                    "review_page",
                    "steps",
                    "counts"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "name": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "active",
                            "paused",
                            "archived"
                        ]
                    },
                    "is_default": {
                        "type": "boolean"
                    },
                    "channels": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "email",
                                "sms"
                            ]
                        }
                    },
                    "review_page": {
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "url": {
                                "type": "string"
                            },
                            "enabled": {
                                "type": "boolean"
                            }
                        },
                        "type": "object"
                    },
                    "from_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "reply_to": {
                        "type": "string",
                        "nullable": true
                    },
                    "track_opens": {
                        "type": "boolean"
                    },
                    "email_branding": {
                        "type": "boolean"
                    },
                    "email_accent": {
                        "description": "The campaign's own button color `#rrggbb`; null = the review page accent.",
                        "type": "string",
                        "nullable": true
                    },
                    "email_look": {
                        "description": "What the emails show now.",
                        "properties": {
                            "accent": {
                                "type": "string"
                            },
                            "on_accent": {
                                "type": "string"
                            },
                            "accent_source": {
                                "type": "string",
                                "enum": [
                                    "campaign",
                                    "review_page",
                                    "default",
                                    "off"
                                ]
                            },
                            "logo_url": {
                                "type": "string",
                                "nullable": true
                            },
                            "logo_width": {
                                "type": "integer"
                            },
                            "logo_height": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "steps": {
                        "type": "array",
                        "items": {
                            "properties": {
                                "delay_hours": {
                                    "type": "integer"
                                },
                                "email_subject": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "email_body": {
                                    "type": "string",
                                    "nullable": true
                                },
                                "button_label": {
                                    "description": "null = \"Leave a review\"",
                                    "type": "string",
                                    "nullable": true
                                },
                                "sms_body": {
                                    "description": "The fixed Grades.com text of the step (read-only).",
                                    "type": "string"
                                }
                            },
                            "type": "object"
                        }
                    },
                    "sms_text": {
                        "properties": {
                            "editable": {
                                "type": "boolean"
                            },
                            "sender": {
                                "type": "string"
                            }
                        },
                        "type": "object"
                    },
                    "counts": {
                        "description": "`requests` = every request made with the campaign; `sent` = those whose first message went out.",
                        "properties": {
                            "requests": {
                                "type": "integer"
                            },
                            "sent": {
                                "type": "integer"
                            },
                            "scheduled": {
                                "type": "integer"
                            },
                            "active": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewRequest": {
                "description": "A review request (`request()`). `held_reason` only while a pending request is held by the sending allowance; `held` only in the answer of a single send.",
                "required": [
                    "id",
                    "status",
                    "campaign",
                    "contact",
                    "channels",
                    "trigger",
                    "messages"
                ],
                "properties": {
                    "held_reason": {
                        "type": "string"
                    },
                    "id": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "scheduled",
                            "active",
                            "completed",
                            "stopped",
                            "cancelled"
                        ]
                    },
                    "stop_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "campaign": {
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "active",
                                    "paused",
                                    "archived"
                                ]
                            }
                        },
                        "type": "object"
                    },
                    "contact": {
                        "properties": {
                            "id": {
                                "type": "string",
                                "format": "uuid"
                            },
                            "name": {
                                "type": "string",
                                "nullable": true
                            },
                            "email": {
                                "type": "string",
                                "nullable": true
                            },
                            "phone": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "channels": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": [
                                "email",
                                "sms"
                            ]
                        }
                    },
                    "trigger": {
                        "type": "string"
                    },
                    "external_ref": {
                        "type": "string",
                        "nullable": true
                    },
                    "next_step": {
                        "type": "integer"
                    },
                    "next_send_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "clicked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "opened_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "visited_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "reviewed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "review": {
                        "description": "The review the request led to; null = none (yet).",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "site": {
                                "type": "string"
                            },
                            "site_name": {
                                "type": "string"
                            },
                            "rating": {
                                "type": "integer",
                                "nullable": true
                            },
                            "author": {
                                "type": "string",
                                "nullable": true
                            },
                            "published_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "messages": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/V1ReviewRequestMessage"
                        }
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "held": {
                        "$ref": "#/components/schemas/V1ReviewRequestHold"
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestHold": {
                "description": "Why requests wait instead of going out; null when nothing holds them.",
                "required": [
                    "reason",
                    "message"
                ],
                "properties": {
                    "reason": {
                        "type": "string",
                        "enum": [
                            "sending_disabled",
                            "plan_upgrade_required",
                            "sending_paused",
                            "campaign_paused",
                            "review_page_disabled"
                        ]
                    },
                    "message": {
                        "type": "string"
                    }
                },
                "type": "object",
                "nullable": true
            },
            "V1ReviewRequestMessage": {
                "description": "One message (step and channel) of a review request.",
                "required": [
                    "step",
                    "channel",
                    "status"
                ],
                "properties": {
                    "step": {
                        "type": "integer"
                    },
                    "channel": {
                        "type": "string",
                        "enum": [
                            "email",
                            "sms"
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "sent",
                            "skipped",
                            "failed",
                            "delivered",
                            "bounced",
                            "complained"
                        ]
                    },
                    "to": {
                        "type": "string",
                        "nullable": true
                    },
                    "skip_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "error": {
                        "description": "Only for `failed` messages.",
                        "type": "string",
                        "nullable": true
                    },
                    "skip_note": {
                        "description": "Only for `skipped` messages.",
                        "type": "string",
                        "nullable": true
                    },
                    "sent_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "delivered_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "opened_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "clicked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "bounced_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "complained_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewRequestOptOut": {
                "description": "One row of the opt-out history (never deleted; revoking only dates it).",
                "required": [
                    "id",
                    "channel",
                    "address",
                    "reason",
                    "final"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "channel": {
                        "type": "string",
                        "enum": [
                            "email",
                            "sms"
                        ]
                    },
                    "address": {
                        "type": "string"
                    },
                    "reason": {
                        "type": "string"
                    },
                    "contact_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "revoked_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "revoked_reason": {
                        "type": "string",
                        "nullable": true
                    },
                    "revoke_note": {
                        "type": "string",
                        "nullable": true
                    },
                    "final": {
                        "type": "boolean"
                    }
                },
                "type": "object"
            },
            "V1PublicReview": {
                "required": [
                    "uuid",
                    "source",
                    "source_name",
                    "site",
                    "rating",
                    "text",
                    "author",
                    "avatar",
                    "published_at",
                    "external_url"
                ],
                "properties": {
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "source": {
                        "description": "The collector that stored the review: an internal id (`yelp_apify`, `google_maps`, `api`, ...) that may change. Show `source_name` and filter by `site`.",
                        "type": "string",
                        "example": "yelp_apify"
                    },
                    "source_name": {
                        "description": "Display name of the review platform, e.g. `Google`, `Yelp`, `Direct` (added by the business through the API), `Grades.com`.",
                        "type": "string",
                        "example": "Yelp"
                    },
                    "site": {
                        "description": "The review platform: `google`, `yelp`, `facebook`, `bbb`, ..., `direct` (added by the business through the API) or `grades` (left on Grades.com). The same for every collector of one platform (Client Hub Google reviews are `google`); use it for logos and filters.",
                        "type": "string",
                        "example": "yelp"
                    },
                    "rating": {
                        "type": "integer",
                        "nullable": true,
                        "maximum": 5,
                        "minimum": 1
                    },
                    "text": {
                        "type": "string",
                        "nullable": true
                    },
                    "author": {
                        "type": "string",
                        "example": "Jane D.",
                        "nullable": true
                    },
                    "avatar": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "published_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "external_url": {
                        "type": "string",
                        "format": "url",
                        "nullable": true
                    },
                    "response_text": {
                        "description": "The business's public reply.",
                        "type": "string",
                        "nullable": true
                    },
                    "response_date": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1Review": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1PublicReview"
                    },
                    {
                        "properties": {
                            "title": {
                                "type": "string",
                                "nullable": true
                            },
                            "response_author": {
                                "type": "string",
                                "nullable": true
                            },
                            "hidden": {
                                "description": "Hidden from public displays (`hide_in_widget`).",
                                "type": "boolean"
                            },
                            "edited_at": {
                                "description": "When the reviewer last edited the review on the platform.",
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "deleted_at": {
                                "description": "When the review disappeared from the platform.",
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "removed_at": {
                                "description": "When Grades found the review removed from the platform (same as `deleted_at`). Removed reviews are listed only with `include_removed=1`.",
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "removal_reason": {
                                "description": "Why the review is removed: `removed_from_source` (no longer returned by the review site), `deleted_by_owner` (the business deleted it from its list), `source_removed` (the business disconnected its review site; the review is kept in the archive). Null while the review is live.",
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "removed_from_source",
                                    "deleted_by_owner",
                                    "source_removed"
                                ]
                            },
                            "created_at": {
                                "description": "When the review reached Grades.com (collected from its site, pushed by the Client Hub, sent through the API or left on Grades.com: see `arrival`). A review sent through the API was not collected or verified by Grades.com.",
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "tags": {
                                "description": "Tags on the review (www/docs/review-tags.md): `kind` manual (people) or auto (grades.com), `group` custom / topic / flag / service, `source` manual / auto / service, `confidence` of an auto tag.",
                                "type": "array",
                                "items": {
                                    "properties": {
                                        "slug": {
                                            "type": "string",
                                            "example": "service:roofing"
                                        },
                                        "name": {
                                            "type": "string",
                                            "example": "Roofing"
                                        },
                                        "color": {
                                            "type": "string",
                                            "example": "teal"
                                        },
                                        "kind": {
                                            "type": "string",
                                            "enum": [
                                                "manual",
                                                "auto"
                                            ]
                                        },
                                        "group": {
                                            "type": "string",
                                            "enum": [
                                                "custom",
                                                "topic",
                                                "flag",
                                                "service"
                                            ]
                                        },
                                        "source": {
                                            "type": "string",
                                            "enum": [
                                                "manual",
                                                "auto",
                                                "service"
                                            ]
                                        },
                                        "confidence": {
                                            "type": "number",
                                            "nullable": true
                                        }
                                    },
                                    "type": "object"
                                }
                            },
                            "sentiment": {
                                "description": "positive, neutral, negative or mixed (null until analyzed).",
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "positive",
                                    "neutral",
                                    "negative",
                                    "mixed"
                                ]
                            },
                            "site_name": {
                                "description": "The name owners read for the review platform (`site`): the brand, \"Reviews on Grades.com\" (`grades`), \"Added via API\" (`direct`) or \"Imported\" (a file import).",
                                "type": "string",
                                "example": "Google"
                            },
                            "source_kind": {
                                "description": "Where the review is FROM: `site` (a review site, named in `origin_name`), `grades` (left on Grades.com), `own_system` (the business own system, named by the label it was created with), `unknown` (sent through the API or imported without saying where from). How it got here is `arrival`.",
                                "type": "string",
                                "enum": [
                                    "site",
                                    "grades",
                                    "own_system",
                                    "unknown"
                                ]
                            },
                            "source_phrase": {
                                "description": "Where the review is from, in words: \"on Google\", \"on Yelp\", \"on Grades.com\", \"from your WooCommerce store\", or \"source not given (added through the API)\" / \"source not given (imported from a file)\". Never \"on Added via API\".",
                                "type": "string"
                            },
                            "origin_name": {
                                "description": "The name of where the review is from (\"Google\", \"Grades.com\", the own-system label), null when not given.",
                                "type": "string",
                                "nullable": true
                            },
                            "arrival": {
                                "description": "How the review reached Grades.com: `collected` (from its site), `hub` (pushed by the Client Hub), `api` (sent through the API), `import` (a file import), `review_page` (left on the review page).",
                                "type": "string",
                                "enum": [
                                    "collected",
                                    "hub",
                                    "api",
                                    "import",
                                    "review_page"
                                ]
                            },
                            "text_policy": {
                                "description": "`aggregate`: a source shown only as a rating and a link (Yelp) whose `text`, `author`, `avatar` and `response_text` are withheld (send `yelp_consent=true` after recording the Yelp consent). `yelp_consent`: that text is included after consent, for internal use only. Null for every other review.",
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                    "aggregate",
                                    "yelp_consent"
                                ]
                            },
                            "text_hint": {
                                "description": "Why the text is withheld and how to get it (with `text_policy: aggregate`), else null.",
                                "type": "string",
                                "nullable": true
                            },
                            "language": {
                                "description": "The review's language (ISO 639-1), null when it cannot be told.",
                                "type": "string",
                                "example": "es",
                                "nullable": true
                            },
                            "text_en": {
                                "description": "Machine translation of `text` into English (\"Translated by AI\", docs/review-agent.md \"Languages\"): null when the review is in English, its language cannot be told, the text is withheld, or no translation was made yet (`translation.status` `missing`: POST .../reviews/{review}/translation).",
                                "type": "string",
                                "nullable": true
                            },
                            "translation": {
                                "oneOf": [
                                    {
                                        "$ref": "#/components/schemas/V1Translation"
                                    },
                                    {
                                        "type": "object",
                                        "nullable": true,
                                        "enum": [
                                            null
                                        ]
                                    }
                                ]
                            },
                            "reply": {
                                "description": "The business's reply, null when there is none. `status` `published`: the review site shows it (`response_text`); `saved`: saved in Grades.com and not posted to the site (a site without a reply API, or `publish: false`): the review counts as replied, the owner still posts it on the site. `text` is withheld with `text_policy: aggregate`. `has_company_response` filters on the same rule.",
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "published",
                                            "saved"
                                        ]
                                    },
                                    "text": {
                                        "type": "string",
                                        "nullable": true
                                    },
                                    "replied_at": {
                                        "type": "string",
                                        "format": "date-time",
                                        "nullable": true
                                    }
                                },
                                "type": "object",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1ReviewSiteCandidate": {
                "description": "A domain of the site radar (`radar:site-report`) in API v1.",
                "required": [
                    "id",
                    "domain",
                    "status",
                    "classification",
                    "qualifies",
                    "score"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "domain": {
                        "type": "string",
                        "example": "vagaro.com"
                    },
                    "site_slug": {
                        "description": "The catalog / radar site name, when known.",
                        "type": "string",
                        "nullable": true
                    },
                    "label": {
                        "type": "string",
                        "nullable": true
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "new",
                            "building",
                            "verified",
                            "ignored",
                            "not_reviews"
                        ]
                    },
                    "classification": {
                        "description": "Guess: customer_reviews, employer_reviews, aggregator (republishes another site), directory, booking (scheduler, gift cards), social, own_site (a company website) or unknown.",
                        "type": "string"
                    },
                    "classification_reasons": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "qualifies": {
                        "description": "Customer reviews AND (cited by an AI answer OR in Google's top 20): \"we should have it\".",
                        "type": "boolean"
                    },
                    "score": {
                        "type": "number",
                        "format": "float"
                    },
                    "companies_count": {
                        "type": "integer"
                    },
                    "mentions_count": {
                        "type": "integer"
                    },
                    "review_pages_count": {
                        "type": "integer"
                    },
                    "review_page_share": {
                        "type": "number",
                        "format": "float"
                    },
                    "ai_citations": {
                        "type": "integer"
                    },
                    "engines": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "best_position": {
                        "type": "integer",
                        "nullable": true
                    },
                    "rating_hints": {
                        "type": "integer"
                    },
                    "sample_urls": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "demand_customers": {
                        "description": "Customer companies that need the site (AI answers and radar pages about them, their requests); from the daily `review-sites:demand`, test and directory-only companies never count.",
                        "type": "integer"
                    },
                    "demand_requests": {
                        "description": "Explicit requests (customers and super admins).",
                        "type": "integer"
                    },
                    "first_demand_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_demand_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "demand_sources": {
                        "description": "Companies per source (`ai`, `radar`, `request`, `admin`) and their ids under `company_ids` (capped at 50).",
                        "type": "object"
                    },
                    "notes": {
                        "type": "string",
                        "nullable": true
                    },
                    "first_seen_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "last_seen_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "reported_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1ReviewSite": {
                "required": [
                    "slug",
                    "label",
                    "name",
                    "kind",
                    "source_type",
                    "connect",
                    "url_hosts",
                    "refresh",
                    "display"
                ],
                "properties": {
                    "slug": {
                        "description": "The driver name (`company_sources.driver`).",
                        "type": "string",
                        "example": "healthgrades"
                    },
                    "name": {
                        "description": "Short name used in review lists.",
                        "type": "string",
                        "example": "Healthgrades"
                    },
                    "label": {
                        "description": "Name in the connect dialog.",
                        "type": "string",
                        "example": "Healthgrades"
                    },
                    "kind": {
                        "type": "string",
                        "enum": [
                            "apify",
                            "native"
                        ]
                    },
                    "source_type": {
                        "type": "string",
                        "enum": [
                            "customer_reviews",
                            "employer_reviews",
                            "directory",
                            "aggregator"
                        ]
                    },
                    "connect": {
                        "description": "`url`: the business page URL; `oauth`: owner consent in the dashboard; `token`: G2 API token.",
                        "type": "string",
                        "enum": [
                            "url",
                            "oauth",
                            "token"
                        ]
                    },
                    "url_hosts": {
                        "description": "A profile URL must be on one of these hosts or a subdomain.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "refresh": {
                        "type": "string",
                        "enum": [
                            "daily",
                            "weekly",
                            "minutely"
                        ]
                    },
                    "display": {
                        "properties": {
                            "icon": {
                                "type": "string",
                                "nullable": true
                            },
                            "wordmark": {
                                "type": "string",
                                "nullable": true
                            },
                            "example": {
                                "type": "string",
                                "nullable": true
                            },
                            "input_label": {
                                "type": "string",
                                "nullable": true
                            },
                            "hint": {
                                "type": "string",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1AdminReviewSite": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1ReviewSite"
                    },
                    {
                        "properties": {
                            "origin": {
                                "description": "`config`: defined in code; `catalog`: defined by its row.",
                                "type": "string",
                                "enum": [
                                    "config",
                                    "catalog"
                                ]
                            },
                            "enabled": {
                                "type": "boolean"
                            },
                            "verified": {
                                "description": "Live: connectable, parsed and scheduled.",
                                "type": "boolean"
                            },
                            "live": {
                                "type": "boolean"
                            },
                            "saved": {
                                "description": "False for a code driver that has no row yet.",
                                "type": "boolean"
                            },
                            "profile_patterns": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "actor_id": {
                                "type": "string",
                                "nullable": true
                            },
                            "input_template": {
                                "type": "object",
                                "nullable": true
                            },
                            "field_map": {
                                "type": "object",
                                "nullable": true
                            },
                            "options": {
                                "type": "object",
                                "nullable": true
                            },
                            "schedule_at": {
                                "type": "string",
                                "example": "02:40",
                                "nullable": true
                            },
                            "verification": {
                                "description": "The last verification run: status (running, passed, failed, error), actor, sample_url, item_count, review_count, fields (share per required field), missing, cost_usd, at.",
                                "type": "object",
                                "nullable": true
                            },
                            "notes": {
                                "type": "string",
                                "nullable": true
                            },
                            "updated_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1SiteRequestCase": {
                "description": "A tracked site request as the customer sees it (docs/review-radar.md \"Tracked requests\"): the site, the status, the\ntwo-week due date and our answer. The internal note never leaves the admin area.",
                "required": [
                    "id",
                    "domain",
                    "site_name",
                    "url",
                    "status",
                    "requested_at",
                    "due_at"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "domain": {
                        "type": "string",
                        "example": "repairpal.com"
                    },
                    "site_name": {
                        "type": "string",
                        "example": "RepairPal"
                    },
                    "url": {
                        "description": "The page the business gave.",
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "new",
                            "in_progress",
                            "live",
                            "not_possible"
                        ]
                    },
                    "status_label": {
                        "type": "string",
                        "example": "Requested"
                    },
                    "requested_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "due_at": {
                        "description": "Two weeks after the request: the date www promises.",
                        "type": "string",
                        "format": "date-time"
                    },
                    "days_left": {
                        "description": "Whole days until `due_at` while open (negative once overdue); null when live or not possible.",
                        "type": "integer",
                        "nullable": true
                    },
                    "answer": {
                        "description": "Our answer to the business (always set for `not_possible`).",
                        "type": "string",
                        "nullable": true
                    },
                    "reason": {
                        "description": "`not_possible` only: blocks_collection, no_public_reviews, not_a_review_site, terms_forbid, per_unit_pages, other.",
                        "type": "string",
                        "nullable": true
                    },
                    "live_site": {
                        "description": "`live` only: `collected` = Grades.com collects the site's reviews (connect it in Review sites); `link_only` = a button on the review page, reviews not collected.",
                        "properties": {
                            "kind": {
                                "type": "string",
                                "enum": [
                                    "collected",
                                    "link_only"
                                ]
                            },
                            "slug": {
                                "type": "string"
                            },
                            "name": {
                                "type": "string"
                            }
                        },
                        "type": "object",
                        "nullable": true
                    },
                    "closed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1SourceCandidate": {
                "description": "A review-site profile found by source discovery.",
                "required": [
                    "id",
                    "driver",
                    "display_name",
                    "url",
                    "confidence",
                    "evidence",
                    "status",
                    "connectable",
                    "connected"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "driver": {
                        "type": "string",
                        "example": "yelp"
                    },
                    "display_name": {
                        "type": "string",
                        "example": "Yelp"
                    },
                    "url": {
                        "type": "string",
                        "format": "url"
                    },
                    "confidence": {
                        "description": "0-0.99",
                        "type": "number",
                        "format": "float",
                        "example": 0.85
                    },
                    "evidence": {
                        "description": "How it was found: `sources` (`website`, `google_places`, `google_search`) and, depending on the source, `title`, `snippet`, `query`, `position`, `rating`, `reviews_count`, `website_page`, `anchor_text`, `place_id`, `address`, `google_driver_hint`.",
                        "type": "object"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "new",
                            "accepted",
                            "rejected"
                        ]
                    },
                    "connectable": {
                        "description": "Whether accepting connects it (false for sites Grades cannot fetch yet, e.g. houzz).",
                        "type": "boolean"
                    },
                    "connected": {
                        "description": "The company already has a source of this driver.",
                        "type": "boolean"
                    },
                    "decided_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                },
                "type": "object"
            },
            "V1Source": {
                "description": "A connected review source in API v1, with its parse (sync) state.",
                "required": [
                    "driver",
                    "display_name",
                    "active",
                    "link",
                    "needs_reconnect",
                    "reviews_count",
                    "found_by",
                    "parse"
                ],
                "properties": {
                    "driver": {
                        "type": "string",
                        "example": "google"
                    },
                    "display_name": {
                        "description": "Display name of the review site. A source of Client Hub reviews (`driver` = `api`) is named after its site (`Google`), never `Api`.",
                        "type": "string",
                        "example": "Google"
                    },
                    "site": {
                        "description": "The review platform of the source (`google`, `yelp`, `bbb`, ...; Client Hub sources name their site, an `api` source without one is `direct`, Grades.com reviews `grades`). `driver` is the collector, an internal id that may change; use `site` for logos and filters.",
                        "type": "string",
                        "example": "google"
                    },
                    "active": {
                        "type": "boolean"
                    },
                    "link": {
                        "description": "The business page on the review site.",
                        "type": "string",
                        "nullable": true
                    },
                    "needs_reconnect": {
                        "description": "The source's authorization expired; the owner must reconnect it in the dashboard.",
                        "type": "boolean"
                    },
                    "reviews_count": {
                        "type": "integer"
                    },
                    "found_by": {
                        "description": "`radar` or `discovery` when the source came from the review radar or source discovery (the dashboard badge \"Found by radar\"), `ai_answer` when an AI answer about the business cites it (badge \"Cited by AI\"); null otherwise.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "radar",
                            "discovery",
                            "ai_answer"
                        ]
                    },
                    "auto_connected_at": {
                        "description": "When Grades connected it by itself (auto-connect); null when a person did.",
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "parse": {
                        "properties": {
                            "status": {
                                "description": "`never`: not fetched yet; `in_progress`: the current fetch has not completed (running, or interrupted and resumed on the next run); `finished`: the last fetch completed.",
                                "type": "string",
                                "enum": [
                                    "never",
                                    "in_progress",
                                    "finished"
                                ]
                            },
                            "started_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "finished_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "last_activity_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                            },
                            "expected_reviews_count": {
                                "type": "integer",
                                "nullable": true
                            },
                            "collected_reviews_count": {
                                "type": "integer",
                                "nullable": true
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1RatingStats": {
                "required": [
                    "total",
                    "average_rating",
                    "ratings"
                ],
                "properties": {
                    "total": {
                        "description": "Number of rated reviews.",
                        "type": "integer",
                        "example": 128
                    },
                    "average_rating": {
                        "type": "number",
                        "format": "float",
                        "example": 4.62,
                        "nullable": true
                    },
                    "ratings": {
                        "description": "Count per star rating.",
                        "properties": {
                            "1": {
                                "type": "integer"
                            },
                            "2": {
                                "type": "integer"
                            },
                            "3": {
                                "type": "integer"
                            },
                            "4": {
                                "type": "integer"
                            },
                            "5": {
                                "type": "integer"
                            }
                        },
                        "type": "object"
                    }
                },
                "type": "object"
            },
            "V1Stats": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/V1RatingStats"
                    },
                    {
                        "properties": {
                            "by_source": {
                                "description": "Per source driver (internal ids such as `yelp_apify` or `api`, which mixes Client Hub and Direct reviews). To show sites to people use `by_platform`.",
                                "type": "object",
                                "additionalProperties": {
                                    "$ref": "#/components/schemas/V1RatingStats"
                                }
                            },
                            "by_platform": {
                                "description": "One row per review platform, largest first: the drivers of one platform merged (Yelp collected two ways is one Yelp row, the average weighted by count). `name` is the display name (\"Yelp\", \"BBB\", \"Reviews on Grades.com\", \"Added via API\" for reviews added through the API without a site); `sources` lists the drivers.",
                                "type": "array",
                                "items": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/V1RatingStats"
                                        },
                                        {
                                            "required": [
                                                "platform",
                                                "name",
                                                "sources"
                                            ],
                                            "properties": {
                                                "platform": {
                                                    "type": "string",
                                                    "example": "yelp"
                                                },
                                                "name": {
                                                    "type": "string",
                                                    "example": "Yelp"
                                                },
                                                "sources": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    },
                                                    "example": [
                                                        "yelp_apify",
                                                        "yelp"
                                                    ]
                                                }
                                            },
                                            "type": "object"
                                        }
                                    ]
                                }
                            }
                        },
                        "type": "object"
                    }
                ]
            },
            "V1Translation": {
                "description": "A machine translation for the owner. Always show `label` (\"Translated by AI\") and keep the original visible: the original is the text of record.",
                "required": [
                    "status",
                    "text",
                    "source_language",
                    "target_language",
                    "label",
                    "machine_translated",
                    "model",
                    "created_at",
                    "reason"
                ],
                "properties": {
                    "status": {
                        "description": "`available`: `text` holds the translation; `missing`: not made yet (POST .../translation for a review); `unavailable`: it cannot be made (`reason`).",
                        "type": "string",
                        "enum": [
                            "available",
                            "missing",
                            "unavailable"
                        ]
                    },
                    "text": {
                        "type": "string",
                        "nullable": true
                    },
                    "source_language": {
                        "description": "ISO 639-1.",
                        "type": "string",
                        "example": "es",
                        "nullable": true
                    },
                    "target_language": {
                        "type": "string",
                        "example": "en"
                    },
                    "label": {
                        "type": "string",
                        "example": "Translated by AI"
                    },
                    "machine_translated": {
                        "type": "boolean",
                        "example": true
                    },
                    "model": {
                        "type": "string",
                        "nullable": true
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "reason": {
                        "description": "`language_unsupported`: a healthcare review in a language the clinical scrub cannot read (never sent to a model); `yelp_text`: Yelp text is never sent to a model; `failed`: try again later.",
                        "type": "string",
                        "nullable": true,
                        "enum": [
                            "language_unsupported",
                            "yelp_text",
                            "failed"
                        ]
                    }
                },
                "type": "object"
            }
        },
        "responses": {
            "AIReplyForbidden": {
                "description": "AI reply generation is not allowed for this review",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AIReplyForbiddenResponse"
                        }
                    }
                }
            },
            "AIReplyLimitExceeded": {
                "description": "Monthly AI reply generation limit has been reached",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AIReplyLimitExceededResponse"
                        }
                    }
                }
            },
            "AIReplyServiceBusy": {
                "description": "AI reply generation is temporarily busy (lock contention). Safe to retry.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AIReplyServiceBusyResponse"
                        }
                    }
                }
            },
            "AISettingsIncomplete": {
                "description": "Company AI settings are incomplete — the client should redirect to AI Settings page",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AISettingsIncompleteResponse"
                        }
                    }
                }
            },
            "GeminiApiError": {
                "description": "Upstream AI service error",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/GeminiApiErrorResponse"
                        }
                    }
                }
            },
            "GenerateAIReply": {
                "description": "Generated AI reply text",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/GenerateAIReply"
                        }
                    }
                }
            },
            "AuthorizationError": {
                "description": "Authorization required",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AuthorizationErrorResponse"
                        }
                    }
                }
            },
            "Companies": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompaniesResponse"
                        }
                    }
                }
            },
            "CompanyAlreadyExists": {
                "description": "Company Already Exists",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyAlreadyExistsResponse"
                        }
                    }
                }
            },
            "CompanyEx": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyEx"
                        }
                    }
                }
            },
            "CompanyInvitationNotAccepted": {
                "description": "Company invitation not accepted",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyInvitationNotAcceptedResponse"
                        }
                    }
                }
            },
            "CompanyLogoNotFound": {
                "description": "Company Logo Not Found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyLogoNotFoundResponse"
                        }
                    }
                }
            },
            "CompanyNotFound": {
                "description": "Company Not Found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyNotFoundResponse"
                        }
                    }
                }
            },
            "Company": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Company"
                        }
                    }
                }
            },
            "CompanyUser": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyUser"
                        }
                    }
                }
            },
            "CompanyUsersList": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyUsersList"
                        }
                    }
                }
            },
            "InsufficientPermissions": {
                "description": "Insufficient permissions",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/InsufficientPermissionsResponse"
                        }
                    }
                }
            },
            "UserAlreadyExistsInCompany": {
                "description": "User already exists in company",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UserAlreadyExistsInCompanyResponse"
                        }
                    }
                }
            },
            "CompanyUserNotFound": {
                "description": "Company user not found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CompanyUserNotFoundResponse"
                        }
                    }
                }
            },
            "File": {
                "description": "File binary content",
                "content": {
                    "application/octet-stream": {
                        "schema": {
                            "type": "string",
                            "format": "binary"
                        }
                    }
                }
            },
            "InternalServerError": {
                "description": "Internal Server Error",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/InternalServerErrorResponse"
                        }
                    }
                }
            },
            "NotImplemented": {
                "description": "Not Implemented",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/NotImplementedResponse"
                        }
                    }
                }
            },
            "NotificationNotFound": {
                "description": "Notification Not Found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/NotificationNotFoundResponse"
                        }
                    }
                }
            },
            "Notification": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Notification"
                        }
                    }
                }
            },
            "NotificationSettings": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/NotificationSettings"
                        }
                    }
                }
            },
            "Notifications": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/NotificationsResponse"
                        }
                    }
                }
            },
            "RequestTooLargeError": {
                "description": "Request Too Large",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/RequestTooLargeErrorResponse"
                        }
                    }
                }
            },
            "ResourceNotFound": {
                "description": "Resource Not Found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ResourceNotFoundResponse"
                        }
                    }
                }
            },
            "ImportReviews": {
                "description": "Direct reviews import result",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ImportReviews"
                        }
                    }
                }
            },
            "ReviewEx": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewEx"
                        }
                    }
                }
            },
            "ReviewNotFound": {
                "description": "Review Not Found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewNotFoundResponse"
                        }
                    }
                }
            },
            "Review": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Review"
                        }
                    }
                }
            },
            "Reviews": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsResponse"
                        }
                    }
                }
            },
            "ReviewsStatsByDays": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsStatsByDaysResponse"
                        }
                    }
                }
            },
            "ReviewsStats": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsStatsResponse"
                        }
                    }
                }
            },
            "ReviewReplay": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Review"
                        }
                    }
                }
            },
            "ReviewReplyDelete": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewReplyDelete"
                        }
                    }
                }
            },
            "ReviewReplyShow": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewReplyShow"
                        }
                    }
                }
            },
            "ReviewReplyUpsert": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewReplyUpsert"
                        }
                    }
                }
            },
            "AuthReviewSource": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AuthReviewSource"
                        }
                    }
                }
            },
            "ReviewsSourceNotFound": {
                "description": "Reviews Source Not Found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsSourceNotFoundResponse"
                        }
                    }
                }
            },
            "ReviewsSource": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsSource"
                        }
                    }
                }
            },
            "ReviewsSources": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsSources"
                        }
                    }
                }
            },
            "Successfully": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/SuccessfullyResponse"
                        }
                    }
                }
            },
            "TokenExpired": {
                "description": "Reset token has expired",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/TokenExpiredResponse"
                        }
                    }
                }
            },
            "TokenNotFound": {
                "description": "Reset token not found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/TokenNotFoundResponse"
                        }
                    }
                }
            },
            "UserAlreadyExists": {
                "description": "User Already Exists",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UserAlreadyExistsResponse"
                        }
                    }
                }
            },
            "UserLogin": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/User"
                        }
                    }
                }
            },
            "UserNotFound": {
                "description": "User Not Found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UserNotFoundResponse"
                        }
                    }
                }
            },
            "User": {
                "description": "Successful operation",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/User"
                        }
                    }
                }
            },
            "ValidateError": {
                "description": "Validate Error",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ValidateErrorResponse"
                        }
                    }
                }
            },
            "BillingProblem": {
                "description": "Billing refusal (problem details)",
                "content": {
                    "application/problem+json": {
                        "schema": {
                            "$ref": "#/components/schemas/BillingProblem"
                        }
                    }
                }
            },
            "V1Problem": {
                "description": "Error (problem details)",
                "content": {
                    "application/problem+json": {
                        "schema": {
                            "$ref": "#/components/schemas/Problem"
                        }
                    }
                }
            }
        },
        "parameters": {
            "CompanyPath": {
                "name": "company",
                "in": "path",
                "description": "Company UUID.",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/Uuid"
                }
            },
            "CompanyUserPath": {
                "name": "user",
                "in": "path",
                "description": "User UUID.",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/Uuid"
                }
            },
            "EndDate": {
                "name": "end_date",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "type": "string",
                    "format": "date"
                }
            },
            "IncludeTotalQuantity": {
                "name": "include_total_quantity",
                "in": "query",
                "description": "Include the total number of items in response.",
                "schema": {
                    "type": "boolean",
                    "default": false
                }
            },
            "ItemsPerPage": {
                "name": "items_per_page",
                "in": "query",
                "description": "The number of elements in the response (empty string to output all elements).",
                "allowEmptyValue": true,
                "schema": {
                    "type": "integer",
                    "format": "int32",
                    "default": 10,
                    "minimum": 10
                }
            },
            "NotificationPath": {
                "name": "notification",
                "in": "path",
                "description": "Notification UUID.",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/Uuid"
                }
            },
            "Page": {
                "name": "page",
                "in": "query",
                "description": "Page number for pagination.",
                "schema": {
                    "type": "integer",
                    "format": "int32",
                    "default": 1,
                    "minimum": 1
                }
            },
            "ReportCompany": {
                "name": "company",
                "in": "query",
                "description": "Comma-separated business (company) uuids; default every business the key reaches.",
                "required": false,
                "schema": {
                    "type": "string"
                }
            },
            "ReportStartDate": {
                "name": "start_date",
                "in": "query",
                "description": "YYYY-MM-DD (UTC), inclusive.",
                "required": false,
                "schema": {
                    "type": "string",
                    "format": "date"
                }
            },
            "ReportEndDate": {
                "name": "end_date",
                "in": "query",
                "description": "YYYY-MM-DD (UTC), inclusive.",
                "required": false,
                "schema": {
                    "type": "string",
                    "format": "date"
                }
            },
            "ReportLimit": {
                "name": "limit",
                "in": "query",
                "description": "Rows per page, 1-10000 (default 1000; CSV 10000).",
                "required": false,
                "schema": {
                    "type": "integer",
                    "maximum": 10000,
                    "minimum": 1
                }
            },
            "ReportCursor": {
                "name": "cursor",
                "in": "query",
                "description": "`meta.next_cursor` (JSON) or `X-Next-Cursor` (CSV) of the previous page, with the same filters.",
                "required": false,
                "schema": {
                    "type": "string"
                }
            },
            "ReportPage": {
                "name": "page",
                "in": "query",
                "description": "Page number (1, 2, ...) for tools that cannot follow a cursor; page x limit at most 50,000 rows. Not with `cursor`.",
                "required": false,
                "schema": {
                    "type": "integer",
                    "minimum": 1
                }
            },
            "ReportFormat": {
                "name": "format",
                "in": "query",
                "description": "`json` (default) or `csv` (streamed, header row, next page in `X-Next-Cursor` / `Link: rel=\"next\"`).",
                "required": false,
                "schema": {
                    "type": "string",
                    "enum": [
                        "json",
                        "csv"
                    ]
                }
            },
            "ReportInterval": {
                "name": "interval",
                "in": "query",
                "description": "Period of a time series: `day`, `week` (ISO, Monday) or `month` (default). Without dates: the last 90 days.",
                "required": false,
                "schema": {
                    "type": "string",
                    "enum": [
                        "day",
                        "week",
                        "month"
                    ]
                }
            },
            "ReportKey": {
                "name": "key",
                "in": "query",
                "description": "Only for tools that cannot send a header, and only while REPORTS_URL_KEY_ENABLED is on: a reporting URL key (`gk_live_url_...`, made with \"Usable in a URL\", reviews:read only). Any other key: 401 `url_key_required`. Prefer `Authorization: Bearer`.",
                "required": false,
                "schema": {
                    "type": "string"
                }
            },
            "ReviewEdited": {
                "name": "edited",
                "in": "query",
                "description": "Reviews their author edited (the archive kept at least one earlier version, reason `edited`): `only` = only edited reviews, `exclude` = only reviews never edited. Without it the list has both.",
                "schema": {
                    "type": "string",
                    "enum": [
                        "exclude",
                        "only"
                    ]
                }
            },
            "ReviewsExportFileType": {
                "name": "format",
                "in": "query",
                "description": "File type to export.",
                "required": true,
                "schema": {
                    "type": "string",
                    "enum": [
                        "csv"
                    ]
                }
            },
            "ReviewHasCompanyResponse": {
                "name": "has_company_response",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "type": "boolean"
                }
            },
            "ReviewHideInWidget": {
                "name": "hide_in_widget",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "type": "boolean"
                }
            },
            "ReviewIncludeSource": {
                "name": "include_source",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "type": "boolean",
                    "default": false
                }
            },
            "ReviewIsRecommended": {
                "name": "is_recommended",
                "in": "query",
                "description": "`true` - likes are greater than or equal to dislikes, `false` - dislikes are greater than likes.",
                "schema": {
                    "type": "boolean"
                }
            },
            "ReviewMaxLength": {
                "name": "max_length",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "$ref": "#/components/schemas/ReviewLength"
                }
            },
            "ReviewMaxRating": {
                "name": "max_rating",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "$ref": "#/components/schemas/ReviewRating"
                }
            },
            "ReviewMinLength": {
                "name": "min_length",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "$ref": "#/components/schemas/ReviewLength"
                }
            },
            "ReviewMinRating": {
                "name": "min_rating",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "$ref": "#/components/schemas/ReviewRating"
                }
            },
            "ReviewStatsMonthPath": {
                "name": "month",
                "in": "path",
                "description": "<\\<Description>>",
                "required": true,
                "schema": {
                    "type": "integer",
                    "format": "int32",
                    "maximum": 12,
                    "minimum": 1
                }
            },
            "ReviewsOrderBy": {
                "name": "order_by",
                "in": "query",
                "description": "|-\n Array containing sorting pairs:\n- ort field - (one of the values: `username`, `publishedDate`, `rating`, `hasCompanyResponse`).\n- Sorting direction - from smaller to larger (`asc`) or larger to smaller (`desc`).",
                "explode": false,
                "schema": {
                    "type": "array",
                    "items": {
                        "$ref": "#/components/schemas/ReviewsOrderByItem"
                    },
                    "default": [],
                    "uniqueItems": true
                }
            },
            "ReviewRemoved": {
                "name": "removed",
                "in": "query",
                "description": "Reviews removed from their site (kept in the archive): `exclude` = only reviews still on their site, `only` = only removed ones. Without it the list has both.",
                "schema": {
                    "type": "string",
                    "enum": [
                        "exclude",
                        "only"
                    ]
                }
            },
            "ReviewPath": {
                "name": "review",
                "in": "path",
                "description": "Review UUID.",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/Uuid"
                }
            },
            "ReviewS": {
                "name": "s",
                "in": "query",
                "description": "Search: a case-insensitive part of the review text or of the author name shown (`author`). `%`, `_` and `\\` match themselves.",
                "schema": {
                    "type": "string",
                    "maxLength": 100
                }
            },
            "ReviewSourceDrivers": {
                "name": "source_drivers",
                "in": "query",
                "description": "<\\<Description>>",
                "allowEmptyValue": true,
                "explode": false,
                "schema": {
                    "type": "array",
                    "items": {
                        "$ref": "#/components/schemas/ReviewsSourceDriver"
                    },
                    "default": null,
                    "uniqueItems": true
                }
            },
            "ReviewType": {
                "name": "type",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "type": "string",
                    "enum": [
                        "text",
                        "image",
                        "rating"
                    ]
                }
            },
            "ReviewStatsYearPath": {
                "name": "year",
                "in": "path",
                "description": "<\\<Description>>",
                "required": true,
                "schema": {
                    "type": "integer",
                    "format": "int32",
                    "maximum": 2100,
                    "minimum": 2000
                }
            },
            "ReviewReplyPath": {
                "name": "review",
                "in": "path",
                "description": "Review UUID. Reply is available only for Google reviews.",
                "required": true,
                "schema": {
                    "$ref": "#/components/schemas/Uuid"
                }
            },
            "frontend_redirect_url": {
                "name": "frontend_redirect_url",
                "in": "query",
                "description": "Optional URL to redirect after OAuth completion.",
                "required": false,
                "schema": {
                    "type": "string",
                    "format": "url"
                }
            },
            "ReviewsSourcePath": {
                "name": "source",
                "in": "path",
                "description": "ReviewsSource driver (e.g. google, yelp).",
                "required": true,
                "schema": {
                    "type": "string",
                    "example": "google"
                }
            },
            "SharedIncludeReviewsSources": {
                "name": "include_reviews_sources",
                "in": "query",
                "description": "Add ReviewsSources to the result.",
                "schema": {
                    "type": "boolean",
                    "default": false
                }
            },
            "StartDate": {
                "name": "start_date",
                "in": "query",
                "description": "<\\<Description>>",
                "schema": {
                    "type": "string",
                    "format": "date"
                }
            },
            "V1Cursor": {
                "name": "cursor",
                "in": "query",
                "description": "Opaque `meta.next_cursor` from the previous page. Only valid with the same `sort`.",
                "schema": {
                    "type": "string",
                    "maxLength": 1000
                }
            },
            "V1IncludeDeleted": {
                "name": "include_deleted",
                "in": "query",
                "description": "Also return reviews that have disappeared from the review site (`deleted_at` set).",
                "schema": {
                    "type": "boolean",
                    "default": false
                }
            },
            "V1IncludeRemoved": {
                "name": "include_removed",
                "in": "query",
                "description": "Also return reviews removed from the review site (`removed_at` set); `1`/`true`. Same as `include_deleted`.",
                "schema": {
                    "type": "boolean",
                    "default": false
                }
            },
            "V1Limit": {
                "name": "limit",
                "in": "query",
                "description": "Page size.",
                "schema": {
                    "type": "integer",
                    "format": "int32",
                    "default": 25,
                    "maximum": 100,
                    "minimum": 1
                }
            },
            "V1PublicLimit": {
                "name": "limit",
                "in": "query",
                "description": "Number of reviews.",
                "schema": {
                    "type": "integer",
                    "format": "int32",
                    "default": 10,
                    "maximum": 50,
                    "minimum": 1
                }
            },
            "V1PublicSort": {
                "name": "sort",
                "in": "query",
                "description": "`newest` first, or `best` (highest rating, then newest).",
                "schema": {
                    "type": "string",
                    "default": "newest",
                    "enum": [
                        "newest",
                        "best"
                    ]
                }
            },
            "V1PublicSources": {
                "name": "sources",
                "in": "query",
                "description": "Comma-separated review sites to include, e.g. `google,yelp`. All when omitted.",
                "explode": false,
                "schema": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "pattern": "^[a-z0-9._]+$",
                        "maxLength": 64
                    },
                    "maxItems": 50,
                    "uniqueItems": true
                }
            },
            "V1ReviewSort": {
                "name": "sort",
                "in": "query",
                "description": "Order: `newest` / `oldest` by publish date, `rating_desc` / `rating_asc` by rating (ties newest first).",
                "schema": {
                    "type": "string",
                    "default": "newest",
                    "enum": [
                        "newest",
                        "oldest",
                        "rating_desc",
                        "rating_asc"
                    ]
                }
            },
            "V1AgentActionPath": {
                "name": "action",
                "in": "path",
                "description": "Review agent action uuid.",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "V1AgentLearningPath": {
                "name": "learning",
                "in": "path",
                "description": "Review agent learning uuid.",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "HubClientId": {
                "name": "hubClientId",
                "in": "path",
                "description": "The Hub ID of the client (e.g. `4950`).",
                "required": true,
                "schema": {
                    "type": "string"
                }
            },
            "HubLocationKey": {
                "name": "locationKey",
                "in": "path",
                "description": "`main`, or `gbp:<location id>` for a client with several locations.",
                "required": true,
                "schema": {
                    "type": "string"
                }
            },
            "HubClientCompany": {
                "name": "company",
                "in": "query",
                "description": "Uuid of one company of the client (`GET /v1/hub/clients/{hubClientId}/companies`); any other uuid is 404 `company_not_linked`. Without it, every readable company of the client.",
                "required": false,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "V1IntegrationPlatformPath": {
                "name": "platform",
                "in": "path",
                "description": "Job-done platform.",
                "required": true,
                "schema": {
                    "type": "string",
                    "enum": [
                        "jobber",
                        "housecall_pro",
                        "open_dental",
                        "clio",
                        "square",
                        "hubspot"
                    ]
                }
            },
            "V1ReviewRequestCampaignPath": {
                "name": "campaign",
                "in": "path",
                "description": "Review request campaign uuid, or `default` for the default campaign.",
                "required": true,
                "schema": {
                    "type": "string"
                }
            },
            "V1ReviewRequestContactPath": {
                "name": "contact",
                "in": "path",
                "description": "Review request contact uuid.",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "V1ReviewRequestPath": {
                "name": "request",
                "in": "path",
                "description": "Review request uuid.",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "ShowcaseCount": {
                "name": "count",
                "in": "query",
                "description": "Reviews to return (default 6), capped by the plan (Starter 10, Pro 25, Premium 50).",
                "required": false,
                "schema": {
                    "type": "integer",
                    "maximum": 50,
                    "minimum": 1
                }
            },
            "ShowcaseMinRating": {
                "name": "min_rating",
                "in": "query",
                "description": "Lowest star rating (default 4).",
                "required": false,
                "schema": {
                    "type": "integer",
                    "maximum": 5,
                    "minimum": 1
                }
            },
            "ShowcaseMinLength": {
                "name": "min_length",
                "in": "query",
                "description": "Shortest text in characters (default 40).",
                "required": false,
                "schema": {
                    "type": "integer",
                    "maximum": 2000,
                    "minimum": 0
                }
            },
            "ShowcaseMaxLength": {
                "name": "max_length",
                "in": "query",
                "description": "Longest text in characters (default 600). Longer reviews are left out, never shortened.",
                "required": false,
                "schema": {
                    "type": "integer",
                    "maximum": 5000,
                    "minimum": 40
                }
            },
            "ShowcaseTopic": {
                "name": "topic",
                "in": "query",
                "description": "A service, an attribute (`customer_service`) or a phrase. With fewer than 3 matches the general rules apply and `meta.fallback` says so.",
                "required": false,
                "schema": {
                    "type": "string",
                    "maxLength": 80
                }
            },
            "ShowcaseSites": {
                "name": "sites",
                "in": "query",
                "description": "Comma-separated site keys or drivers (`google,facebook,grades`). Default: every eligible site, never Yelp text. Naming `yelp` asks for `yelp_consent` (authenticated JSON / Markdown only; public surfaces never carry Yelp text).",
                "required": false,
                "schema": {
                    "type": "string"
                }
            },
            "ShowcaseMaxAge": {
                "name": "max_age_days",
                "in": "query",
                "description": "Only reviews published in the last N days.",
                "required": false,
                "schema": {
                    "type": "integer",
                    "maximum": 3650,
                    "minimum": 1
                }
            },
            "ShowcaseLanguage": {
                "name": "language",
                "in": "query",
                "description": "Only reviews written in this language.",
                "required": false,
                "schema": {
                    "type": "string",
                    "enum": [
                        "en",
                        "es",
                        "fr",
                        "pt",
                        "de",
                        "it"
                    ]
                }
            },
            "ShowcaseSeed": {
                "name": "seed",
                "in": "query",
                "description": "A stable shuffle instead of newest first (same seed, same order).",
                "required": false,
                "schema": {
                    "type": "string",
                    "maxLength": 40
                }
            },
            "ShowcaseFormat": {
                "name": "format",
                "in": "query",
                "description": "`json` (default, the envelope), or the raw `html` block, `markdown` or `jsonld`.",
                "required": false,
                "schema": {
                    "type": "string",
                    "enum": [
                        "json",
                        "html",
                        "markdown",
                        "jsonld"
                    ]
                }
            },
            "ShowcaseStyle": {
                "name": "style",
                "in": "query",
                "description": "Style preset of the HTML block (default: the saved showcase's, else `auto`).",
                "required": false,
                "schema": {
                    "type": "string",
                    "enum": [
                        "light",
                        "dark",
                        "auto"
                    ]
                }
            },
            "ShowcaseInclude": {
                "name": "include",
                "in": "query",
                "description": "With `format=json`: comma-separated rendered formats added to `meta.rendered` (`html,markdown,jsonld`).",
                "required": false,
                "schema": {
                    "type": "string"
                }
            },
            "ShowcaseSaved": {
                "name": "showcase",
                "in": "query",
                "description": "A saved showcase (uuid) of the company: its rules and style; other parameters override them.",
                "required": false,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            }
        },
        "requestBodies": {
            "AiSettingsRequestBody": {
                "description": "AI Settings to update — only AI-related fields, no general company data.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AiSettings"
                        }
                    }
                }
            },
            "CompanyLogoRequestBody": {
                "description": "File binary content",
                "content": {
                    "application/octet-stream": {
                        "schema": {
                            "type": "string",
                            "format": "binary"
                        }
                    }
                }
            },
            "CompanyRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Company"
                        }
                    }
                }
            },
            "CreateCompanyRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/CreateCompany"
                        }
                    }
                }
            },
            "InviteUserRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/InviteUserRequest"
                        }
                    }
                }
            },
            "UpdateUserRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UpdateUserRequest"
                        }
                    }
                }
            },
            "NotificationRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Notification"
                        }
                    }
                }
            },
            "NotificationSettingsRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/NotificationSettings"
                        }
                    }
                }
            },
            "ReviewReplyRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewReplyRequest"
                        }
                    }
                }
            },
            "ReviewRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Review"
                        }
                    }
                }
            },
            "ReviewsImportRequestBody": {
                "description": "CSV file with reviews to import",
                "content": {
                    "application/octet-stream": {
                        "schema": {
                            "type": "string",
                            "format": "binary"
                        }
                    }
                }
            },
            "AuthReviewSourceRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AuthReviewSource"
                        }
                    }
                }
            },
            "ReviewsSourceActiveRequestBody": {
                "description": "Whether the source is fetched. Settings are changed through the `/config` endpoint.",
                "required": true,
                "content": {
                    "application/json": {
                        "schema": {
                            "required": [
                                "active"
                            ],
                            "properties": {
                                "active": {
                                    "type": "boolean"
                                }
                            },
                            "type": "object"
                        }
                    }
                }
            },
            "ReviewsSourceConfigRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsSourceConfig"
                        }
                    }
                }
            },
            "ReviewsSourceRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ReviewsSource"
                        }
                    }
                }
            },
            "SendResetPasswordLinkRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/SendResetPasswordLinkRequestBody"
                        }
                    }
                }
            },
            "UpdatePasswordRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UpdatePassword"
                        }
                    }
                }
            },
            "UserLoginRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UserLogin"
                        }
                    }
                }
            },
            "UserRegisterRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UserRegister"
                        }
                    }
                }
            },
            "UserRequestBody": {
                "description": "<\\<Description>>",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/UserUpdate"
                        }
                    }
                }
            }
        },
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "description": "A secret API key (`gk_live_...`) or an MCP OAuth 2.1 access token (RS256 JWT) as `Authorization: Bearer ...`. An API key needs every scope in the operation's `x-required-scopes` (the same strings as the OAuth scopes). Hub routes (`/v1/hub/*`) take only the Client Hub's service key, with one of the abilities in `x-hub-abilities`.",
                "scheme": "bearer"
            },
            "oauth2": {
                "type": "oauth2",
                "description": "The MCP OAuth 2.1 authorization server (issuer `https://app.grades.com/mcp/oauth`, metadata at `/.well-known/oauth-authorization-server`, dynamic client registration, PKCE S256). Its access tokens are sent as `Authorization: Bearer ...` like an API key. `review_pages:read` and `ask:use` are granted to the Grades.com Android app only.",
                "flows": {
                    "authorizationCode": {
                        "authorizationUrl": "https://app.grades.com/mcp/oauth/authorize",
                        "tokenUrl": "https://app.grades.com/mcp/oauth/token",
                        "refreshUrl": "https://app.grades.com/mcp/oauth/token",
                        "scopes": {
                            "reviews:read": "See your reviews, your ratings and the replies to them",
                            "reviews:write": "Reply to reviews for you, draft replies with AI, flag or hide reviews, connect review sites and manage your website widget keys",
                            "companies:read": "See your business details and which review sites are connected",
                            "companies:write": "Add businesses and edit their details",
                            "directory:read": "Look up businesses in the Grades.com directory, with their public listings, grades and rankings",
                            "review_pages:read": "See your businesses and their review pages (name, logo, link and colors), nothing else",
                            "ask:use": "Ask Grades about your reviews (read only; drafts are shown, never posted)",
                            "openid": "See your name and email address",
                            "email": "See your name and email address",
                            "profile": "See your name and email address"
                        }
                    }
                }
            },
            "dashboardSession": {
                "type": "apiKey",
                "description": "The session cookie of the my.grades.com dashboard (sign in at https://my.grades.com). Not for integrations: use an API key or OAuth on the `/v1` routes. A session is not limited by scopes, only by the member's role.",
                "name": "gradescom_session",
                "in": "cookie"
            },
            "publishableKey": {
                "type": "apiKey",
                "description": "Publishable key (`gk_pub_...`) of the public reviews API, as `?key=`.",
                "name": "key",
                "in": "query"
            },
            "publishableKeyHeader": {
                "type": "apiKey",
                "description": "Publishable key (`gk_pub_...`) of the public reviews API, as the `X-Grades-Key` header.",
                "name": "X-Grades-Key",
                "in": "header"
            },
            "reportUrlKey": {
                "type": "apiKey",
                "description": "Reports API only: a reporting URL key (`gk_live_url_...`, scope `reviews:read` only) as `?key=`, for BI tools that cannot send headers. Off unless REPORTS_URL_KEY_ENABLED; any other key in a URL is refused.",
                "name": "key",
                "in": "query"
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        },
        {
            "oauth2": []
        }
    ],
    "tags": [
        {
            "name": "Agent",
            "description": "Review agent for the dashboard (session); same payloads as API v1."
        },
        {
            "name": "Assistant",
            "description": "The dashboard assistant (session)."
        },
        {
            "name": "BrowserSessions",
            "description": "Connected review-site accounts (review agent v2); same payloads as API v1."
        },
        {
            "name": "Discovery",
            "description": "Source discovery for the dashboard (session); same payloads as API v1."
        },
        {
            "name": "Insights",
            "description": "Review Insights for the dashboard (session); same payload as API v1."
        },
        {
            "name": "Menu",
            "description": "The dashboard menu (session)."
        },
        {
            "name": "Radar",
            "description": "Review radar for the dashboard (session); same payloads as API v1."
        },
        {
            "name": "ReviewPages",
            "description": "Review pages for the dashboard (session); same payloads as API v1."
        },
        {
            "name": "Showcase",
            "description": "Review Showcase for the dashboard (session); same payloads as API v1."
        },
        {
            "name": "v1 internal",
            "description": "Browser worker only (service key with `browser:worker`). Review agent v2."
        },
        {
            "name": "Celebration posts",
            "description": "Celebration posts: ready-to-share social posts of milestones, awards and grades."
        },
        {
            "name": "Social Posts",
            "description": "Social Posts from a review: social images, a vertical video and Google Ads banners made from one review (cuts only)."
        },
        {
            "name": "User",
            "description": "Dashboard session: sign-in, sign-up, password reset, sign-out and the signed-in user's profile."
        },
        {
            "name": "Notification",
            "description": "Dashboard session: the signed-in user's notifications and their settings."
        },
        {
            "name": "Company",
            "description": "Dashboard session: the user's businesses, their details, logo and AI settings."
        },
        {
            "name": "ReviewsSource",
            "description": "Dashboard session: the review sites connected to a business."
        },
        {
            "name": "Review",
            "description": "Dashboard session: a business's reviews, their history, export and statistics."
        },
        {
            "name": "Billing",
            "description": "Plans, trials and Stripe billing of a location (dashboard session)."
        },
        {
            "name": "v1 hub",
            "description": "Client Hub integration. The Hub service key only (`hub:*` abilities)."
        },
        {
            "name": "v1",
            "description": "REST API v1. Bearer API key (`gk_live_...`) or MCP OAuth access token."
        },
        {
            "name": "v1 public",
            "description": "Public reviews API for websites. Publishable key (`gk_pub_...`)."
        },
        {
            "name": "ApiKey",
            "description": "Secret API keys of the signed-in user."
        },
        {
            "name": "PublishableKey",
            "description": "Publishable keys for the public reviews API."
        },
        {
            "name": "AIReply",
            "description": "AIReply"
        },
        {
            "name": "Company Users",
            "description": "Company Users"
        },
        {
            "name": "Reviews",
            "description": "Reviews"
        },
        {
            "name": "ReviewReply",
            "description": "ReviewReply"
        },
        {
            "name": "v1 agencies",
            "description": "v1 agencies"
        },
        {
            "name": "v1 directory",
            "description": "v1 directory"
        }
    ],
    "externalDocs": {
        "description": "Developers: REST API, MCP server and webhooks",
        "url": "https://www.grades.com/developers"
    }
}