{ "openapi": "3.1.0", "info": { "title": "Loppee Business Registry API for External Agents", "version": "3.0", "summary": "Business registry and scoped workflow access for customer- and administrator-operated external agents.", "description": "Customers and administrators supply and operate their external agents. Loppee provides scoped API/MCP access and keys only; it does not provide, host, or operate an agent or AI service. Under v3, this access is available at no charge for now. Loppee v3 exposes explicit Verified and Listed business classes. Category recommendations may also contain a reviewed_registry section within the three-mile Free reach and an exclusive fallback_registry section containing at most one unclaimed record; owner-submitted and claimed-but-unpublished Registry records are never fallback results. Exact/genuine-prefix name recommendations preserve direct-entity relevance and may contain identity-reviewed Registry rows without radius entitlement or unrated fallback. Registry businesses retain their explicit claim_status and disclosure and are not currently published as Verified or Listed. Identity-verified reviewer ratings influence quality only within the applicable class or Registry pool. Local category discovery and recommendations require a current precise location proof or handoff, a user-confirmed validated destination authority, or a saved_exact Home location. City/state, ZIP, and saved_coarse locations are neutral area context for business-name disambiguation only: they return no local category or recommendation results, cannot activate Sponsored placement, and record no impressions. A connected assistant's current location comes only from the registered Loppee iPhone; provider IP, caller-supplied coordinates, host metadata, and computer/browser location are rejected as current-location authority. Exact and genuine-prefix business-name lookup remains universal; without precise location it is commercially neutral." }, "servers": [ { "url": "https://loppee.com", "description": "Production" } ], "tags": [ { "name": "Agent Contract" }, { "name": "Discovery" }, { "name": "Trust Cards" }, { "name": "Customer Account" }, { "name": "Business Owner" }, { "name": "Moderated Actions" }, { "name": "Operations" } ], "paths": { "/health": { "get": { "tags": [ "Operations" ], "summary": "Get API health", "description": "Returns a minimal liveness signal plus public service, contract, and build versions. Repository and write-security internals are intentionally omitted.", "responses": { "200": { "description": "HealthResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Agent Contract" ], "summary": "Get OpenAPI spec", "description": "Returns this OpenAPI 3.1 document.", "responses": { "200": { "description": "OpenApiDocument", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/openapi.json": { "get": { "tags": [ "Agent Contract" ], "summary": "Get versioned OpenAPI spec", "description": "Returns this OpenAPI 3.1 document.", "responses": { "200": { "description": "OpenApiDocument", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agent-openapi.json": { "get": { "tags": [ "Agent Contract" ], "summary": "Get least-authority external-agent OpenAPI spec", "description": "Returns the provider-neutral OpenAPI 3.1 contract for connected external agents. The contract exposes opaque iPhone location handoff status and business results, never raw device location.", "responses": { "200": { "description": "OpenApiDocument", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiDocument" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agent-capabilities.json": { "get": { "tags": [ "Agent Contract" ], "summary": "Get agent capabilities", "description": "Returns endpoints, policy links, tool contract, and schema catalog.", "responses": { "200": { "description": "AgentCapabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCapabilities" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agent-policy.json": { "get": { "tags": [ "Agent Contract" ], "summary": "Get agent policy", "description": "Returns recommendation, action, and blocked-behavior policy.", "responses": { "200": { "description": "AgentPolicy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPolicy" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agent-integration.json": { "get": { "tags": [ "Agent Contract" ], "summary": "Get integration package", "description": "Returns API, MCP, docs, examples, and rate-limit integration metadata.", "responses": { "200": { "description": "AgentIntegration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentIntegration" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/agent-monitoring.json": { "get": { "tags": [ "Operations" ], "summary": "Get agent monitoring", "description": "Returns aggregate request/error counters, service/build contract metadata, and the published rate-limit policy. Per-route activity and repository internals are intentionally omitted.", "responses": { "200": { "description": "AgentMonitoring", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMonitoring" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/pricing": { "get": { "tags": [ "Agent Contract" ], "summary": "Get published pricing & promotions", "description": "This field follows the Loppee v3 Verified and Listed contract.", "responses": { "200": { "description": "PricingResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/content": { "get": { "tags": [ "Agent Contract" ], "summary": "Get published site content", "description": "Returns only currently published, validation-safe public presentation blocks. Missing or invalid blocks are omitted so clients can use their shipped defaults. Content controls presentation only and never changes trust, verification, ranking, reach, or review weight. Public and cacheable by the service; no key required.", "responses": { "200": { "description": "PublicContentResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicContentResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/businesses/index.json": { "get": { "tags": [ "Discovery" ], "summary": "List published business index", "description": "Returns published profiles only. Directory listings are intentionally excluded. Cursor-paginated: pass limit (1-100, default 100) and cursor (the next_cursor value from the previous page); next_cursor is present only when more pages exist, so small registries fit in one unpaginated response. Public-read by default; some deployments may require a Loppee API key.", "responses": { "200": { "description": "BusinessIndex", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessIndex" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum businesses per page (1-100, default 100).", "schema": { "type": "number" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor from the previous page's next_cursor. Omit for the first page.", "schema": { "type": "string" } } ] } }, "/v1/search": { "get": { "tags": [ "Discovery" ], "summary": "Search businesses", "description": "Taxonomy/category discovery requires a current-location proof or handoff, a Sponsored-neutral validated-destination authority that preserves plan-based organic reach, or saved_exact Home. A connected-assistant current-location handoff from the registered Loppee iPhone is organic-only: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Coarse city/state and ZIP are neutral context only and return no local category results, no Sponsored placement, and no impressions. Provider IP, caller coordinates, host metadata, and computer/browser current location are never accepted as connected-assistant current-location authority. Exact and genuine-prefix business-name lookup remains universal and commercially neutral without precise location. Within the three-mile Free reach, category search may include Registry records that retain exact claim_status and disclosure and remain outside published Verified/Listed classes; identity-verified reviewer ratings can order quality within the Registry pool, while payment has no quality influence. Exposure-plan payment changes discovery reach, gallery capacity, and, when Sponsored ordering is active, labeled position-weighted exposure only within the same verification class and verified-review reputation band. It never changes business-profile publication, verification, review authority, reputation, moderation, class ordering, or reputation band. Loppee Jobs is a separate optional paid product; its billing affects job-posting activation only and never business verification or directory ranking.", "responses": { "200": { "description": "SearchResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "For a local category or recommendation lane, current-location, validated-destination, or saved_exact authority is required. Coarse context fails closed with precise_location_required and sponsored_exposure_recorded=false. Exact/genuine-prefix name lookup remains universal." }, "403": { "description": "The location authority is not bound to the same active scoped consumer-agent key or authenticated customer session, or that authority is no longer active." }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search. Category terms auto-route to precise-location-gated discovery; otherwise exact and genuine-prefix business-name lookup is universal and commercially neutral without precise location.", "schema": { "description": "Free-text search. Category terms auto-route to precise-location-gated discovery; otherwise exact and genuine-prefix business-name lookup is universal and commercially neutral without precise location.", "type": "string", "minLength": 1 } }, { "name": "category", "in": "query", "required": false, "description": "Taxonomy category alias or category term. Resolved categories require recognized current-location, validated-destination, or saved_exact authority; coarse context returns no local results.", "schema": { "description": "Taxonomy category alias or category term. Resolved categories require recognized current-location, validated-destination, or saved_exact authority; coarse context returns no local results.", "type": "string", "minLength": 1 } }, { "name": "intent", "in": "query", "required": false, "description": "Routing hint: auto (default), category, or name; legacy value aliases remain accepted.", "schema": { "description": "Routing hint: auto (default), category, or name; legacy value aliases remain accepted.", "type": "string", "enum": [ "auto", "category", "name", "search_category", "category_search", "lookup", "lookup_business", "business_name" ] } }, { "name": "search_intent", "in": "query", "required": false, "description": "Deprecated alias of intent; legacy value aliases remain accepted.", "deprecated": true, "schema": { "description": "Deprecated alias of intent; legacy value aliases remain accepted.", "type": "string", "enum": [ "auto", "category", "name", "search_category", "category_search", "lookup", "lookup_business", "business_name" ] } }, { "name": "city", "in": "query", "required": false, "description": "City context. With state, it can disambiguate a business name but cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "schema": { "description": "City context. With state, it can disambiguate a business name but cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "type": "string", "minLength": 1 } }, { "name": "state", "in": "query", "required": false, "description": "Two-letter US state or territory code. With city, this is neutral area context for business-name disambiguation; it is not precise local-discovery authority.", "schema": { "description": "Two-letter US state or territory code. With city, this is neutral area context for business-name disambiguation; it is not precise local-discovery authority.", "type": "string", "pattern": "^(?:AL|AK|AZ|AR|CA|CO|CT|DE|FL|GA|HI|ID|IL|IN|IA|KS|KY|LA|ME|MD|MA|MI|MN|MS|MO|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PA|RI|SC|SD|TN|TX|UT|VT|VA|WA|WV|WI|WY|DC|AS|GU|MP|PR|VI)$" } }, { "name": "zip", "in": "query", "required": false, "description": "5-digit US ZIP (ZIP+4 accepted). Its ZCTA centroid is neutral area context for business-name disambiguation only; it cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "schema": { "description": "5-digit US ZIP (ZIP+4 accepted). Its ZCTA centroid is neutral area context for business-name disambiguation only; it cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "type": "string", "pattern": "^\\d{5}(?:-\\d{4})?$" } }, { "name": "radius_miles", "in": "query", "required": false, "description": "Requested area radius. It never substitutes for recognized current-location, validated-destination, or saved_exact authority. Universal name lookup may use it only as neutral context.", "schema": { "description": "Requested area radius. It never substitutes for recognized current-location, validated-destination, or saved_exact authority. Universal name lookup may use it only as neutral context.", "type": "number", "minimum": 0.1, "maximum": 500 } }, { "name": "include_directory_listings", "in": "query", "required": false, "description": "Include honestly labeled, unverified directory listings for discovery.", "schema": { "default": true, "description": "Include honestly labeled, unverified directory listings for discovery.", "type": "boolean" } }, { "name": "paid_only", "in": "query", "required": false, "description": "Consumer-directory paid-exposure presentation filter.", "schema": { "description": "Consumer-directory paid-exposure presentation filter.", "type": "boolean" } }, { "name": "consumer_reach", "in": "query", "required": false, "description": "Consumer web/mobile directory policy: ignore caller radius_miles and enforce each result's exact plan/branch radius for category and partial/fuzzy name discovery. Literal exact and genuine-prefix entity-name matches remain universal and commercially neutral. Agents should normally omit it.", "schema": { "description": "Consumer web/mobile directory policy: ignore caller radius_miles and enforce each result's exact plan/branch radius for category and partial/fuzzy name discovery. Literal exact and genuine-prefix entity-name matches remain universal and commercially neutral. Agents should normally omit it.", "type": "boolean" } }, { "name": "location_selection", "in": "query", "required": false, "description": "The customer's explicit location choice. Current, a user-confirmed validated destination handoff, or Home when reach_precision=exact can authorize local category/recommendation discovery. Provided city/ZIP and coarse Home are neutral area context for business-name disambiguation only. Ask exactly: 'Where should I search? For local categories, use your current location, enter a different service address securely in Loppee, or use Home only when it is marked exact. Another city/ZIP is for area context or business-name lookup only.' Exact and genuine-prefix business-name lookup is exempt.", "schema": { "description": "The customer's explicit location choice. Current, a user-confirmed validated destination handoff, or Home when reach_precision=exact can authorize local category/recommendation discovery. Provided city/ZIP and coarse Home are neutral area context for business-name disambiguation only. Ask exactly: 'Where should I search? For local categories, use your current location, enter a different service address securely in Loppee, or use Home only when it is marked exact. Another city/ZIP is for area context or business-name lookup only.' Exact and genuine-prefix business-name lookup is exempt.", "type": "string", "enum": [ "saved", "current", "destination", "provided" ] } }, { "name": "saved_location_ref", "in": "query", "required": false, "description": "Opaque saved-location reference returned by get_location_options. Required with location_selection=saved. Only kind=saved_exact authorizes local category/recommendation reach; coarse saved kinds remain neutral context. It contains no address, ZIP, latitude, or longitude.", "schema": { "description": "Opaque saved-location reference returned by get_location_options. Required with location_selection=saved. Only kind=saved_exact authorizes local category/recommendation reach; coarse saved kinds remain neutral context. It contains no address, ZIP, latitude, or longitude.", "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "location_handoff_id", "in": "query", "required": false, "description": "Opaque current-location or validated-destination handoff approved by the consumer. Both authorize plan-based organic local category/recommendation reach and both are Sponsored-neutral: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Current location must come from the registered Loppee iPhone. Requires the same active scoped consumer-agent connection that created it. Do not combine it with lat/lng, ZIP, city, or state; Loppee uses the point privately and never returns an address or coordinates to the agent.", "schema": { "description": "Opaque current-location or validated-destination handoff approved by the consumer. Both authorize plan-based organic local category/recommendation reach and both are Sponsored-neutral: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Current location must come from the registered Loppee iPhone. Requires the same active scoped consumer-agent connection that created it. Do not combine it with lat/lng, ZIP, city, or state; Loppee uses the point privately and never returns an address or coordinates to the agent.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "location_proof_id", "in": "query", "required": false, "description": "Opaque short-lived current-location or validated-destination proof. It may be created by an authenticated Loppee customer or same-origin browser flow; the attested iOS lane remains current-location only. Do not combine it with any other location input; the address and exact point remain private.", "schema": { "description": "Opaque short-lived current-location or validated-destination proof. It may be created by an authenticated Loppee customer or same-origin browser flow; the attested iOS lane remains current-location only. Do not combine it with any other location input; the address and exact point remain private.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor returned in next_cursor by the previous v3 search page. Omit for the first page.", "schema": { "description": "Opaque cursor returned in next_cursor by the previous v3 search page. Omit for the first page.", "type": "string", "minLength": 1, "maxLength": 4096 } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count from 1 to 50.", "schema": { "default": 10, "description": "Maximum result count from 1 to 50.", "type": "integer", "minimum": 1, "maximum": 50 } } ] } }, "/v1/business-claim/candidates": { "get": { "tags": [ "Business Owner" ], "summary": "Find an existing business to claim", "description": "Resolves a business name against public Loppee Registry subjects before an ownership claim. Each candidate includes its source-backed street_address and ZIP when available so same-name branches can be distinguished; missing address data is returned as null and never inferred. City/state or ZIP is optional neutral disambiguation only. Results are capped at six; payment, consumer radius, Sponsored placement, and impression accounting are excluded. Selecting a result grants no ownership—the authenticated claim action performs the separate proof step. Public, no key required.", "responses": { "200": { "description": "SearchResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Business name, 2-200 characters.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "Optional city for neutral same-name disambiguation.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Optional two-letter US state or territory code.", "schema": { "type": "string" } }, { "name": "zip", "in": "query", "required": false, "description": "Optional 5-digit US ZIP or ZIP+4 for neutral disambiguation.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum candidates, 1-6; default 6.", "schema": { "type": "number" } } ] } }, "/v1/suggest": { "get": { "tags": [ "Discovery" ], "summary": "Suggest published business names and taxonomy categories", "description": "Cheap, deterministic typeahead for the public search UI. Business-name rows are lexical name_query labels from visible Registry inventory, never branch selections, profile authority, rankings, recommendations, reach decisions, Sponsored placement, or impressions. Selecting one runs the normal exact intent=name search. Category suggestions come from the closed taxonomy.", "responses": { "200": { "description": "SuggestResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Typeahead text, capped at 120 characters. Taxonomy suggestions start at two characters; business-name name_query suggestions start at three so pg_trgm can use an indexable trigram.", "schema": { "type": "string" } } ] } }, "/v1/geo/context": { "get": { "tags": [ "Discovery" ], "summary": "Get coarse request location context", "description": "Returns an approximate, request-scoped US city centroid inferred from the caller IP when available, or available=false. The IP and result are not persisted. This is a discovery fallback only; it never changes trust, verification, review weight, or paid reach. Public, no key required, and no-store.", "responses": { "200": { "description": "GeoContextResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoContextResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/customer": { "get": { "tags": [ "Customer Account" ], "summary": "Get my private customer profile", "description": "Returns the authenticated customer's own allowlisted private profile fields. A stored profile-photo locator is never returned: avatar_url is null or a short-lived signed display URL for a private customer-avatars object. Never public and never available to an owner, admin, or another customer's agent.", "responses": { "200": { "description": "CustomerAccountUpsertResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountUpsertResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseCustomerBearer": [] } ] }, "post": { "tags": [ "Moderated Actions" ], "summary": "Create or update my customer account", "description": "Creates or partially updates the signed-in customer's private profile. The bearer identity and normalized email are authoritative; body fields cannot select another user. A signature-verified AAL1 customer session may create or update the profile when customer MFA is optional; the deployment-wide required mode still enforces AAL2. avatar_url accepts an empty string to remove the photo or a client-cropped square PNG/JPEG/WebP/GIF data URI (at most 300 KB decoded and 512 px per side). Loppee validates the bytes, stores them in private object storage, and returns only a short-lived signed display URL. The avatar-only path cannot create/reactivate an account or change authentication identity, roles, trust, reviews, ranking, or recommendation eligibility. Customer, owner, and admin identities are pairwise exclusive by user id and normalized email.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountUpsertRequest" } } } }, "responses": { "200": { "description": "CustomerAccountUpsertResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAccountUpsertResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "503": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/location": { "get": { "tags": [ "Customer Account" ], "summary": "Get safe saved service location metadata", "description": "Returns only availability, a user-facing label, kind/precision, timestamp, and an opaque saved-location reference. Only kind=saved_exact can authorize local category/recommendation reach. Coarse kinds remain neutral context. It never returns ZIP, address, latitude, or longitude.", "responses": { "200": { "description": "SavedLocationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedLocationResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseCustomerBearer": [] } ] }, "put": { "tags": [ "Customer Account" ], "summary": "Save a coarse ZIP or confirmed current service location", "description": "A signed-in customer may save a coarse ZIP or promote the same account's short-lived customer location proof into an encrypted exact service anchor. Only the exact form can authorize local category/recommendation reach and Sponsored exposure; coarse ZIP cannot and records no impressions. Raw coordinates are not accepted and no location is claimed as a verified residence.", "responses": { "200": { "description": "SavedLocationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedLocationResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedLocationRequest" } } } } }, "delete": { "tags": [ "Customer Account" ], "summary": "Clear saved home location", "description": "Clears and cryptographically scrubs the customer's saved service location. The response contains no ZIP, address, latitude, or longitude.", "responses": { "200": { "description": "SavedLocationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedLocationResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseCustomerBearer": [] } ] } }, "/v1/taxonomy/suggest": { "get": { "tags": [ "Discovery" ], "summary": "Suggest exact taxonomy categories", "description": "Deterministic typeahead over the closed category taxonomy (leaf categories only). Use it to pick the 1-3 exact category aliases required when creating or editing a business (category_aliases on update_business_profile; taxonomyCategoryAliases on business applications). Vocabulary discovery only — returns no business data and never requires a key.", "responses": { "200": { "description": "TaxonomySuggestionsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomySuggestionsResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Category search text, e.g. plumber, HVAC, nail salon. Minimum 2 characters.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum suggestions to return (1-20, default 8).", "schema": { "type": "number" } } ] } }, "/v1/jobs": { "get": { "tags": [ "Customer Jobs" ], "summary": "Search jobs", "description": "Find active job postings from claimed, verified, published employers. Viewing jobs requires an active personal customer session; business-owner and administrator sessions are not customer credentials. Payment controls posting eligibility only and never ranking.", "responses": { "200": { "description": "JobsSearchResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobsSearchResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Role/keyword search across job title, description, category, skills, and location. Typo-tolerant via trigram word similarity.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Field/domain filter resolved against the same closed category taxonomy as businesses (aliases + synonyms); unresolvable terms fall back to free-text category matching.", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "City filter.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Two-letter US state filter.", "schema": { "type": "string" } }, { "name": "zip", "in": "query", "required": false, "description": "5-digit US ZIP filter, matched against the posting's postal code.", "schema": { "type": "string" } }, { "name": "radius_miles", "in": "query", "required": false, "description": "Optional radius applied only to an accepted first-party or opaque Loppee location authority. Connected assistants cannot supply coordinates or use provider/computer IP as customer location; remote roles remain separately controlled by include_remote.", "schema": { "type": "number" } }, { "name": "workplace_type", "in": "query", "required": false, "description": "on_site, hybrid, or remote.", "schema": { "type": "string" } }, { "name": "employment_type", "in": "query", "required": false, "description": "full_time, part_time, contract, temporary, internship, or seasonal.", "schema": { "type": "string" } }, { "name": "experience_level", "in": "query", "required": false, "description": "Experience-level filter (substring match, e.g. entry, senior).", "schema": { "type": "string" } }, { "name": "salary_min", "in": "query", "required": false, "description": "Annualized USD salary floor (hourly compares at x2080, monthly at x12). Jobs without a disclosed salary are excluded when set.", "schema": { "type": "number" } }, { "name": "salary_max", "in": "query", "required": false, "description": "Annualized USD salary ceiling.", "schema": { "type": "number" } }, { "name": "posted_within_days", "in": "query", "required": false, "description": "Only roles published within the last N days (1-365).", "schema": { "type": "number" } }, { "name": "include_remote", "in": "query", "required": false, "description": "Default true: remote roles bypass ZIP/radius filters. Set false to exclude them.", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "required": false, "description": "relevance (default, fit + recency) or newest. Both are commercially neutral.", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "required": false, "description": "Exact posting lookup — the id behind the /jobs/{job_id} page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count from 1 to 50.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset into the ranked result set.", "schema": { "type": "number" } } ] } }, "/v1/jobs/{job_id}/apply": { "post": { "tags": [ "Moderated Actions" ], "summary": "Apply to job", "description": "Apply to an active, non-expired job as a signed-in consumer. The seeker is never charged. Resumes enter private quarantine and are unavailable to employers until a clean scan completes; later access uses a separate, scoped short-lived-URL endpoint.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationRequest" } } } }, "responses": { "200": { "description": "JobApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "Loppee job posting id.", "schema": { "type": "string" } } ] } }, "/v1/recommend": { "get": { "tags": [ "Discovery" ], "summary": "Recommend businesses", "description": "Local category recommendations require a current-location proof or handoff, a Sponsored-neutral validated-destination authority that preserves plan-based organic reach, or saved_exact Home. A connected-assistant current-location handoff from the registered Loppee iPhone is organic-only: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Coarse location context cannot return local recommendations, activate Sponsored placement, or record impressions. Exact and genuine-prefix entity-name lookup remains universal and commercially neutral without precise location. Reviewed Registry records may fill category recommendations within the three-mile Free reach while retaining their exact claim-state disclosure and remaining outside published Verified/Listed classes. At most one claim-state-accurately warned fallback is allowed only after all higher-authority pools are empty. In exact/genuine-prefix name recommendations, identity-reviewed Registry records may participate in direct-entity relevance without reach_eligibility; unrated fallback, Sponsored placement, and paid exposure are forbidden. Exposure-plan payment changes discovery reach, gallery capacity, and, when Sponsored ordering is active, labeled position-weighted exposure only within the same verification class and verified-review reputation band. It never changes business-profile publication, verification, review authority, reputation, moderation, class ordering, or reputation band. Loppee Jobs is a separate optional paid product; its billing affects job-posting activation only and never business verification or directory ranking.", "responses": { "200": { "description": "SearchResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationResponse" } } } }, "400": { "description": "For a local category or recommendation lane, current-location, validated-destination, or saved_exact authority is required. Coarse context fails closed with precise_location_required and sponsored_exposure_recorded=false. Exact/genuine-prefix name lookup remains universal." }, "403": { "description": "The location authority is not bound to the same active scoped consumer-agent key or authenticated customer session, or that authority is no longer active." }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text search across the published pool. Exact and genuine-prefix name lookup remains universal; category recommendations require precise location authority.", "schema": { "description": "Free-text search across the published pool. Exact and genuine-prefix name lookup remains universal; category recommendations require precise location authority.", "type": "string", "minLength": 1 } }, { "name": "category", "in": "query", "required": false, "description": "Business category or taxonomy term. Local recommendations require recognized current-location, validated-destination, or saved_exact authority.", "schema": { "description": "Business category or taxonomy term. Local recommendations require recognized current-location, validated-destination, or saved_exact authority.", "type": "string", "minLength": 1 } }, { "name": "city", "in": "query", "required": false, "description": "City context. With state, it can disambiguate a business name but cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "schema": { "description": "City context. With state, it can disambiguate a business name but cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "type": "string", "minLength": 1 } }, { "name": "state", "in": "query", "required": false, "description": "Two-letter US state or territory code. With city, this is neutral area context for business-name disambiguation; it is not precise local-discovery authority.", "schema": { "description": "Two-letter US state or territory code. With city, this is neutral area context for business-name disambiguation; it is not precise local-discovery authority.", "type": "string", "pattern": "^(?:AL|AK|AZ|AR|CA|CO|CT|DE|FL|GA|HI|ID|IL|IN|IA|KS|KY|LA|ME|MD|MA|MI|MN|MS|MO|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PA|RI|SC|SD|TN|TX|UT|VT|VA|WA|WV|WI|WY|DC|AS|GU|MP|PR|VI)$" } }, { "name": "zip", "in": "query", "required": false, "description": "5-digit US ZIP (ZIP+4 accepted). Its ZCTA centroid is neutral area context for business-name disambiguation only; it cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "schema": { "description": "5-digit US ZIP (ZIP+4 accepted). Its ZCTA centroid is neutral area context for business-name disambiguation only; it cannot enable local category/recommendation reach, Sponsored placement, or impressions.", "type": "string", "pattern": "^\\d{5}(?:-\\d{4})?$" } }, { "name": "radius_miles", "in": "query", "required": false, "description": "Requested area radius. It never substitutes for recognized current-location, validated-destination, or saved_exact authority. Universal name lookup may use it only as neutral context.", "schema": { "description": "Requested area radius. It never substitutes for recognized current-location, validated-destination, or saved_exact authority. Universal name lookup may use it only as neutral context.", "type": "number", "minimum": 0.1, "maximum": 500 } }, { "name": "allowed_action", "in": "query", "required": false, "description": "Require a published allowed action such as recommend or call_business.", "schema": { "description": "Require a published allowed action such as recommend or call_business.", "type": "string", "minLength": 1 } }, { "name": "location_selection", "in": "query", "required": false, "description": "The customer's explicit location choice. Current, a user-confirmed validated destination handoff, or Home when reach_precision=exact can authorize local category/recommendation discovery. Provided city/ZIP and coarse Home are neutral area context for business-name disambiguation only. Ask exactly: 'Where should I search? For local categories, use your current location, enter a different service address securely in Loppee, or use Home only when it is marked exact. Another city/ZIP is for area context or business-name lookup only.' Exact and genuine-prefix business-name lookup is exempt.", "schema": { "description": "The customer's explicit location choice. Current, a user-confirmed validated destination handoff, or Home when reach_precision=exact can authorize local category/recommendation discovery. Provided city/ZIP and coarse Home are neutral area context for business-name disambiguation only. Ask exactly: 'Where should I search? For local categories, use your current location, enter a different service address securely in Loppee, or use Home only when it is marked exact. Another city/ZIP is for area context or business-name lookup only.' Exact and genuine-prefix business-name lookup is exempt.", "type": "string", "enum": [ "saved", "current", "destination", "provided" ] } }, { "name": "saved_location_ref", "in": "query", "required": false, "description": "Opaque saved-location reference returned by get_location_options. Required with location_selection=saved. Only kind=saved_exact authorizes local category/recommendation reach; coarse saved kinds remain neutral context. It contains no address, ZIP, latitude, or longitude.", "schema": { "description": "Opaque saved-location reference returned by get_location_options. Required with location_selection=saved. Only kind=saved_exact authorizes local category/recommendation reach; coarse saved kinds remain neutral context. It contains no address, ZIP, latitude, or longitude.", "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "location_handoff_id", "in": "query", "required": false, "description": "Opaque current-location or validated-destination handoff approved by the consumer. Both authorize plan-based organic local category/recommendation reach and both are Sponsored-neutral: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Current location must come from the registered Loppee iPhone. Requires the same active scoped consumer-agent connection that created it. Do not combine it with lat/lng, ZIP, city, or state; Loppee uses the point privately and never returns an address or coordinates to the agent.", "schema": { "description": "Opaque current-location or validated-destination handoff approved by the consumer. Both authorize plan-based organic local category/recommendation reach and both are Sponsored-neutral: no Sponsored ordering or labels, click/recommendation attribution, or exposure accounting. Current location must come from the registered Loppee iPhone. Requires the same active scoped consumer-agent connection that created it. Do not combine it with lat/lng, ZIP, city, or state; Loppee uses the point privately and never returns an address or coordinates to the agent.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "location_proof_id", "in": "query", "required": false, "description": "Opaque short-lived current-location or validated-destination proof. It may be created by an authenticated Loppee customer or same-origin browser flow; the attested iOS lane remains current-location only. Do not combine it with any other location input; the address and exact point remain private.", "schema": { "description": "Opaque short-lived current-location or validated-destination proof. It may be created by an authenticated Loppee customer or same-origin browser flow; the attested iOS lane remains current-location only. Do not combine it with any other location input; the address and exact point remain private.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum result count from 1 to 50.", "schema": { "default": 10, "description": "Maximum result count from 1 to 50.", "type": "integer", "minimum": 1, "maximum": 50 } } ] } }, "/v1/businesses/{business_id}/trust-card.json": { "get": { "tags": [ "Trust Cards" ], "summary": "Get Trust Card by business id", "description": "Returns one Published Trust Card or one visible Registry-page Trust Card by business id. Registry responses preserve exact claim_status and disclosure, remain outside the Published Verified/Listed classes, and never fabricate missing business facts. Unknown, hidden, merged, and admin-intake records return 404. Public-read by default; some deployments may require a Loppee API key.", "responses": { "200": { "description": "TrustCard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustCard" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Loppee business id.", "schema": { "type": "string" } } ] } }, "/v1/businesses/{business_id}/reviews.json": { "get": { "tags": [ "Trust Cards" ], "summary": "Get business reviews (paginated, star-filterable)", "description": "Returns the public review page for one Published business or one visible Registry-page business. Reviewer identity verified by Passkey or verified phone supplies a separate quality-ordering authority; interaction-backed verified_review_count remains a distinct fact and payment has no quality influence. Registry responses preserve exact business_claim_status and remain outside the Published Verified/Listed classes. Reviews from identity-verified reviewers can influence search and recommendation quality. They do not verify, claim, or publish this business, and they do not prove a transaction. Supports newest-first pagination and optional rating filters without exposing reviewer PII.", "responses": { "200": { "description": "BusinessReviewsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessReviewsResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Loppee business id.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number (default 1). Out-of-range pages return an honest empty page.", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "Reviews per page (1-50, default 5).", "schema": { "type": "number" } }, { "name": "rating", "in": "query", "required": false, "description": "Star-rating filter: comma-separated whole values 1-5, e.g. rating=1 or rating=4,5. Omit for all ratings.", "schema": { "type": "string" } } ] } }, "/v1/businesses/{business_id}/deals.json": { "get": { "tags": [ "Trust Cards" ], "summary": "Get active business deals", "description": "Returns the active public deals/coupons for one published business. Deals are available independently of the exposure plan in v3. Sponsored ordering is active only within the same verification class and verified-review reputation band. Sponsored results are labeled, eligible Free businesses retain at least 25% of position-weighted exposure within that band, and direct business-name lookup is not rotated. Public-read by default; some deployments may require a Loppee API key.", "responses": { "200": { "description": "BusinessDealsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDealsResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Loppee business id.", "schema": { "type": "string" } } ] } }, "/v1/domains/{domain_key}/trust-card.json": { "get": { "tags": [ "Trust Cards" ], "summary": "Get Trust Card by domain key", "description": "Returns one published Trust Card by normalized domain key. Public-read by default; some deployments may require a Loppee API key.", "responses": { "200": { "description": "DomainTrustCardResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainTrustCardResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "domain_key", "in": "path", "required": true, "description": "Normalized domain key such as eliteacllc-com.", "schema": { "type": "string" } } ] } }, "/v1/actions/save-business": { "post": { "tags": [ "Moderated Actions" ], "summary": "Save a business", "description": "Attach a business to a customer or service-agent account shortlist workflow. Round-trips with /v1/actions/list-saved-businesses and /v1/actions/unsave-business.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveBusinessRequest" } } } }, "responses": { "200": { "description": "SaveBusinessResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveBusinessResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/list-saved-businesses": { "post": { "tags": [ "Moderated Actions" ], "summary": "List saved businesses", "description": "List the calling account's own saved-business shortlist, newest first — the read half of save-business. Read-only despite the POST verb.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSavedBusinessesRequest" } } } }, "responses": { "200": { "description": "SavedBusinessesResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedBusinessesResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/unsave-business": { "post": { "tags": [ "Moderated Actions" ], "summary": "Unsave a business", "description": "This field follows the Loppee v3 Verified and Listed contract.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsaveBusinessRequest" } } } }, "responses": { "200": { "description": "UnsaveBusinessResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnsaveBusinessResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/message-request": { "post": { "tags": [ "Moderated Actions" ], "summary": "Send message to a business", "description": "Send a customer message directly to any eligible published business's Loppee inbox. Messaging is available on every v3 exposure plan; payment never changes messaging access, business class, ranking, or review authority. Repeat sends append to the same conversation, and replies are read through /v1/actions/list-my-conversations.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } }, "responses": { "200": { "description": "MessageResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/list-my-conversations": { "post": { "tags": [ "Moderated Actions" ], "summary": "List my conversations", "description": "List the calling customer account's own business conversations with replies, newest first — the read half of message-request. Follow pagination.next_cursor until pagination.has_more=false to traverse older history; conversation_id performs one exact scoped lookup and cannot be combined with cursor. Read-only despite the POST verb.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMyConversationsRequest" } } } }, "responses": { "200": { "description": "ConversationsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/review": { "post": { "tags": [ "Moderated Actions" ], "summary": "Submit registered customer-agent review", "description": "Submit a registered customer-agent review for a published business or a visible Registry-page business. Registry-page submissions require customer_confirmed=true. Reviewer-quality authority requires Passkey or verified-phone identity verification and is disclosed separately from interaction evidence. Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRequest" } } } }, "responses": { "200": { "description": "ReviewResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/job-application": { "post": { "tags": [ "Moderated Actions" ], "summary": "Apply to job as consumer agent", "description": "Apply to an active, non-expired job on behalf of the calling customer account. Requires a customer personal agent key with apply_to_job. The seeker is never charged; resumes enter private quarantine and are unavailable to employers until a clean scan completes.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentJobApplicationRequest" } } } }, "responses": { "200": { "description": "JobApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/list-my-job-applications": { "post": { "tags": [ "Moderated Actions" ], "summary": "List my job applications", "description": "List privacy-minimized summaries of the calling customer account's own job applications, newest first, with employer-set status and pollable resume-scan state. Email, cover note, resume metadata/content/path, and signed URLs are never returned. Requires a customer personal agent key. Read-only despite the POST verb.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMyJobApplicationsRequest" } } } }, "responses": { "200": { "description": "JobApplicationsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationsResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/withdraw-job-application": { "post": { "tags": [ "Moderated Actions" ], "summary": "Withdraw my job application", "description": "Withdraw one of the calling customer account's own job applications. Idempotent (already_withdrawn=true on repeat): the application row is retained as withdrawn, while any pending or active resume file and private metadata are permanently deleted. Returns a privacy-minimized summary. Requires a customer personal agent key.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawJobApplicationRequest" } } } }, "responses": { "200": { "description": "WithdrawJobApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawJobApplicationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/public-review": { "post": { "tags": [ "Moderated Actions" ], "summary": "Submit registered customer review", "description": "Submit a signed-in customer review for a published business or a visible Registry-page business. Registry-page submissions require customer_confirmed=true. Reviewer-quality authority requires Passkey or verified-phone identity verification and is disclosed separately from interaction evidence. Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicReviewRequest" } } } }, "responses": { "200": { "description": "ReviewResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/confirm-interaction": { "post": { "tags": [ "Moderated Actions" ], "summary": "Record a Loppee contact", "description": "This field follows the Loppee v3 Verified and Listed contract.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRecordedRequest" } } } }, "responses": { "200": { "description": "ContactRecordedResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRecordedResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/promote-verified-transaction": { "post": { "tags": [ "Moderated Actions" ], "summary": "Promote independently verified transaction evidence", "description": "Requires an AAL2 customer session plus genuine independent or two-sided completion evidence already stored as evidence_id for this business. A customer assertion, message, click, missed-contact record, or self-checkbox is insufficient and cannot self-mint verified status.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteVerifiedTransactionRequest" } } } }, "responses": { "200": { "description": "PromoteVerifiedTransactionResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromoteVerifiedTransactionResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/business-claim": { "post": { "tags": [ "Moderated Actions" ], "summary": "Submit business claim", "description": "Queue a business-owner claim. Requires an AAL2 owner session; customer identities are rejected.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessClaimRequest" } } } }, "responses": { "200": { "description": "BusinessClaimResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessClaimResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/business-application": { "post": { "tags": [ "Moderated Actions" ], "summary": "Submit business application", "description": "Submit owner evidence and intake data for admin verification. Requires an AAL2 owner session; customer identities are rejected.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessApplicationRequest" } } } }, "responses": { "200": { "description": "BusinessApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessApplicationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/commercial-click": { "post": { "tags": [ "Moderated Actions" ], "summary": "Record commercial click", "description": "Record website, call, profile, claim, Trust Card, or badge click analytics.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercialClickRequest" } } } }, "responses": { "200": { "description": "CommercialClickResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommercialClickResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/business-message": { "post": { "tags": [ "Moderated Actions" ], "summary": "Message a business", "description": "Send a registered customer message to a business's owner/agent inbox. Requires a Supabase customer bearer token (the sender identity is derived from the token, not the body).", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicMessageRequest" } } } }, "responses": { "200": { "description": "MessageResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/agent-access-request": { "post": { "tags": [ "Moderated Actions" ], "summary": "Request agent access", "description": "Submit a public request for a scoped agent API key (organization, agent, developer email, use case). Validated + rate-limited; queued for admin review.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccessRequest" } } } }, "responses": { "200": { "description": "AgentAccessResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccessResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/agent-connection-test": { "post": { "tags": [ "Moderated Actions" ], "summary": "Test a scoped agent key", "description": "Validates a scoped agent key through the same resolver used by MCP and returns only its resolved identity and scope metadata. Supply the key in X-LOPPEE-API-Key or Authorization: Bearer; the optional body key is a UI fallback. Keys are never accepted in the URL and the raw key is never returned or logged. Missing and invalid keys are normal ok=false responses. Rate-limited per caller IP.", "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionTestRequest" } } } }, "responses": { "200": { "description": "AgentConnectionTestResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionTestResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "X-LOPPEE-API-Key", "in": "header", "required": false, "description": "Loppee-issued scoped API key for a customer- or administrator-operated external agent. The key grants access only; Loppee does not provide the agent or AI service. Prefer this header (or Authorization: Bearer) over the body fallback.", "schema": { "type": "string" } } ] } }, "/v1/actions/claim-verification/send": { "post": { "tags": [ "Moderated Actions" ], "summary": "Send claim verification code", "description": "Request a one-time contact-verification code. Under trust model v3, SMS goes only to the stored business phone and email goes only to the authenticated active owner's server-derived account email; neither destination is accepted from the request body. Both require a caller-generated request_id UUID and return the challenge_id that must be presented unchanged. The legacy status code_sent means provider acceptance only; provider_status and recipient_delivery_confirmed state that explicitly. Owner email verifies Contact only and never grants claim control, entity, licence, or a class directly. Requires the claim owner's AAL2 bearer token.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimVerificationSendRequest" } } } }, "responses": { "200": { "description": "ClaimVerificationSendResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimVerificationSendResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/claim-verification/verify": { "post": { "tags": [ "Moderated Actions" ], "summary": "Verify claim verification code", "description": "Verify a one-time code. The compatible v2 path may grant an open claim. Under trust model v3, the exact challenge_id returned by the send request is mandatory; owner email is restricted to an already-approved exact owner with active business membership and records Contact evidence only. The database authority, never the caller, derives the resulting class. Requires the claim owner's AAL2 bearer token.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimVerificationVerifyRequest" } } } }, "responses": { "200": { "description": "ClaimVerificationVerifyResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimVerificationVerifyResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/job-applications": { "get": { "tags": [ "Moderated Actions" ], "summary": "List my job applications", "description": "Lists the signed-in consumer's own job applications and statuses only.", "responses": { "200": { "description": "JobApplicationsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationsResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum applications to return.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "number" } } ] } }, "/v1/account/job-applications/{application_id}": { "get": { "tags": [ "Moderated Actions" ], "summary": "View my job application", "description": "Returns one signed-in consumer job application only.", "responses": { "200": { "description": "JobApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "Job application id.", "schema": { "type": "string" } } ] } }, "/v1/account/job-applications/{application_id}/resume-url": { "post": { "tags": [ "Moderated Actions" ], "summary": "Get my resume signed URL", "description": "Returns a short-lived signed URL for the applicant's own private resume file.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "JobResumeSignedUrlResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResumeSignedUrlResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "Job application id.", "schema": { "type": "string" } } ] } }, "/v1/account/job-applications/{application_id}/withdraw": { "post": { "tags": [ "Moderated Actions" ], "summary": "Withdraw my job application", "description": "Withdraws the signed-in consumer's own job application.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "JobApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "Job application id.", "schema": { "type": "string" } } ] } }, "/v1/account/conversations/{conversation_id}/attachments": { "post": { "tags": [ "Moderated Actions" ], "summary": "Attach a private file to my business conversation", "description": "Uploads one content-validated JPG, PNG, WebP, or PDF (10MB maximum) to the signed-in customer's own conversation. Storage is private and this contact remains trust-neutral.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } } ] } }, "/v1/account/conversations/{conversation_id}/attachments/{attachment_id}/url": { "post": { "tags": [ "Moderated Actions" ], "summary": "Open my private chat attachment", "description": "Returns a 10-minute signed URL after re-authorizing the signed-in customer against the conversation.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentUrlResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentUrlResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } }, { "name": "attachment_id", "in": "path", "required": true, "description": "Attachment id.", "schema": { "type": "string" } } ] } }, "/v1/account/conversations/{conversation_id}/report": { "post": { "tags": [ "Moderated Actions" ], "summary": "Report a business conversation", "description": "This field follows the Loppee v3 Verified and Listed contract.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReportRequest" } } } }, "responses": { "200": { "description": "ConversationReportResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReportResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } } ] } }, "/v1/account/conversations/{conversation_id}/close": { "post": { "tags": [ "Moderated Actions" ], "summary": "Close my business conversation", "description": "Closes the signed-in customer's conversation. Closing is reversible by sending a new message and never verifies a transaction or changes trust.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "ConversationCloseResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationCloseResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } } ] } }, "/v1/owner/dashboard": { "get": { "tags": [ "Business Owner" ], "summary": "Get my business-owner dashboard", "description": "Returns the complete dashboard state for businesses the signed-in owner is authorized to manage. The server derives business scope from the owner identity; callers cannot request another business id. Private customer contact details appear only where the customer sent that owner's business a message or review and never enter public Trust Cards. Omit owner_rejection_reason_version for the legacy submission-item shape; set it to 1 only when the client accepts the controlled ownerReasonCode field.", "security": [ { "SupabaseOwnerBearer": [] } ], "responses": { "200": { "description": "OwnerDashboardResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerDashboardResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "owner_rejection_reason_version", "in": "query", "required": false, "description": "Optional additive-field capability. Version 1 allows rejected ownerEvidenceSubmissions items to include controlled ownerReasonCode; omission preserves the legacy item shape.", "schema": { "type": "string", "enum": [ "1" ] } } ] } }, "/v1/owner/messages/{interaction_id}/workflow": { "post": { "tags": [ "Moderated Actions" ], "summary": "Update customer-conversation workflow", "description": "Updates only the signed-in owner's operational status or priority for a customer conversation belonging to that owner's business. Contact and workflow metadata have zero trust weight and never verify a transaction.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationWorkflowRequest" } } } }, "responses": { "200": { "description": "ConversationWorkflowResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationWorkflowResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } } ] } }, "/v1/owner/messages/{interaction_id}/attachments": { "post": { "tags": [ "Moderated Actions" ], "summary": "Attach a private file to a customer conversation", "description": "Uploads one content-validated JPG, PNG, WebP, or PDF (10MB maximum) to a conversation belonging to the signed-in owner's business. The file is private and carries zero trust weight.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } } ] } }, "/v1/owner/messages/{interaction_id}/attachments/{attachment_id}/url": { "post": { "tags": [ "Moderated Actions" ], "summary": "Open a private customer-chat attachment", "description": "Returns a 10-minute signed URL after re-authorizing the signed-in owner against the conversation.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentUrlResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentUrlResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } }, { "name": "attachment_id", "in": "path", "required": true, "description": "Attachment id.", "schema": { "type": "string" } } ] } }, "/v1/owner/messages/{interaction_id}/report": { "post": { "tags": [ "Moderated Actions" ], "summary": "Report a customer conversation", "description": "This field follows the Loppee v3 Verified and Listed contract.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReportRequest" } } } }, "responses": { "200": { "description": "ConversationReportResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationReportResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "description": "Customer conversation id.", "schema": { "type": "string" } } ] } }, "/v1/owner/support/{conversation_id}/attachments": { "post": { "tags": [ "Moderated Actions" ], "summary": "Attach a private file to my support case", "description": "Uploads one content-validated JPG, PNG, WebP, or PDF (10MB maximum) to the signed-in owner's own Loppee Support case.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Support conversation id.", "schema": { "type": "string" } } ] } }, "/v1/owner/support/{conversation_id}/attachments/{attachment_id}/url": { "post": { "tags": [ "Moderated Actions" ], "summary": "Open my private support attachment", "description": "Returns a 10-minute signed URL after re-authorizing the signed-in owner against the support case.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentUrlResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentUrlResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Support conversation id.", "schema": { "type": "string" } }, { "name": "attachment_id", "in": "path", "required": true, "description": "Attachment id.", "schema": { "type": "string" } } ] } }, "/v1/owner/notifications": { "get": { "tags": [ "Operations" ], "summary": "List owner notifications", "description": "Lists PII-safe owner notification rows only for businesses owned by the signed-in owner.", "responses": { "200": { "description": "OwnerNotificationsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerNotificationsResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Owned business filter.", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "required": false, "description": "When true, return unread notifications only.", "schema": { "type": "boolean" } }, { "name": "type", "in": "query", "required": false, "description": "Notification event-type filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum notifications to return.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "number" } } ] } }, "/v1/owner/notifications/{notification_id}/read": { "post": { "tags": [ "Moderated Actions" ], "summary": "Mark owner notification read", "description": "Marks one owner notification as read after verifying it belongs to the signed-in owner.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "OwnerNotificationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerNotificationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "notification_id", "in": "path", "required": true, "description": "Owner notification id.", "schema": { "type": "string" } } ] } }, "/v1/owner/notification-settings": { "post": { "tags": [ "Moderated Actions" ], "summary": "Update owner notification settings", "description": "Updates owner email/webhook channel settings and event subscriptions for the owner's business.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerNotificationSettingsRequest" } } } }, "responses": { "200": { "description": "OwnerNotificationSettingsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerNotificationSettingsResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/webhooks": { "post": { "tags": [ "Moderated Actions" ], "summary": "Register owner-agent webhook", "description": "Registers an HTTPS owner-agent webhook endpoint after SSRF validation and returns the signing secret once.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerWebhookRegistrationRequest" } } } }, "responses": { "200": { "description": "OwnerWebhookRegistrationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerWebhookRegistrationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/webhooks/{endpoint_id}/rotate-secret": { "post": { "tags": [ "Moderated Actions" ], "summary": "Rotate owner-agent webhook secret", "description": "Rotates one owner-agent webhook signing secret and returns the replacement once.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "OwnerWebhookRegistrationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerWebhookRegistrationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "Owner webhook endpoint id.", "schema": { "type": "string" } } ] } }, "/v1/owner/webhooks/{endpoint_id}/disable": { "post": { "tags": [ "Moderated Actions" ], "summary": "Disable owner-agent webhook", "description": "Disables one webhook endpoint after verifying it belongs to the signed-in owner.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "OwnerWebhookEndpointResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerWebhookEndpointResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "description": "Owner webhook endpoint id.", "schema": { "type": "string" } } ] } }, "/v1/owner/job-applications": { "get": { "tags": [ "Operations" ], "summary": "List owner job applications", "description": "Lists applications only for jobs owned by the signed-in business owner.", "responses": { "200": { "description": "JobApplicationsResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationsResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "Owned business filter.", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "required": false, "description": "Owned job-posting filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Application-status filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum applications to return.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset.", "schema": { "type": "number" } } ] } }, "/v1/owner/job-applications/{application_id}": { "get": { "tags": [ "Operations" ], "summary": "View owner job application", "description": "Returns one application only when it belongs to a job owned by the signed-in business owner.", "responses": { "200": { "description": "JobApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "Job application id.", "schema": { "type": "string" } } ] } }, "/v1/owner/job-applications/{application_id}/resume-url": { "post": { "tags": [ "Moderated Actions" ], "summary": "Get applicant resume signed URL", "description": "Returns a short-lived signed URL for a private resume file only to the target employer.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "JobResumeSignedUrlResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResumeSignedUrlResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "Job application id.", "schema": { "type": "string" } } ] } }, "/v1/owner/job-applications/{application_id}/status": { "post": { "tags": [ "Moderated Actions" ], "summary": "Update application status", "description": "Lets the target employer move an application through viewed, shortlisted, rejected, or hired with audit metadata.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationStatusRequest" } } } }, "responses": { "200": { "description": "JobApplicationResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobApplicationResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "application_id", "in": "path", "required": true, "description": "Job application id.", "schema": { "type": "string" } } ] } }, "/v1/admin/agent-dashboard": { "get": { "tags": [ "Operations" ], "summary": "Get admin agent dashboard", "description": "Returns service-agent accounts, masked keys, usage, and billing state for a human AAL2 admin or a scoped admin-agent key with the explicit read permission.", "responses": { "200": { "description": "AdminAgentDashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminAgentDashboard" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ] } }, "/v1/admin/support/{conversation_id}/workflow": { "post": { "tags": [ "Operations" ], "summary": "Update support-case workflow", "description": "Updates category, priority, response SLA, or waiting-on state for one owner-support case. Human AAL2 support permission required.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportWorkflowRequest" } } } }, "responses": { "200": { "description": "SupportWorkflowResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportWorkflowResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Support conversation id.", "schema": { "type": "string" } } ] } }, "/v1/admin/support/{conversation_id}/internal-notes": { "post": { "tags": [ "Operations" ], "summary": "Add private support note", "description": "Adds a staff-only operational note. Notes are excluded from owner, public, Trust Card, REST discovery, and MCP payloads. Human AAL2 support permission required.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportInternalNoteRequest" } } } }, "responses": { "200": { "description": "SupportInternalNoteResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportInternalNoteResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Support conversation id.", "schema": { "type": "string" } } ] } }, "/v1/admin/support/{conversation_id}/attachments": { "post": { "tags": [ "Operations" ], "summary": "Attach a private file to a support case", "description": "Uploads one content-validated JPG, PNG, WebP, or PDF (10MB maximum) to an owner-support case. Human AAL2 support permission required.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Support conversation id.", "schema": { "type": "string" } } ] } }, "/v1/admin/support/{conversation_id}/attachments/{attachment_id}/url": { "post": { "tags": [ "Operations" ], "summary": "Open a private support attachment", "description": "Returns a 10-minute signed URL after re-authorizing the human AAL2 support user against the case.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "ChatAttachmentUrlResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatAttachmentUrlResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "Support conversation id.", "schema": { "type": "string" } }, { "name": "attachment_id", "in": "path", "required": true, "description": "Attachment id.", "schema": { "type": "string" } } ] } }, "/v1/admin/agent-keys": { "post": { "tags": [ "Operations" ], "summary": "Create scoped agent API key", "description": "Creates one scoped agent API key and returns the raw key once. Human AAL2 admin only; admin-agent keys cannot issue credentials.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentApiKeyRequest" } } } }, "responses": { "200": { "description": "CreateAgentApiKeyResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentApiKeyResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "tags": [ "Operations" ], "summary": "List agent API keys", "description": "List agent API keys. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "q query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "used", "in": "query", "required": false, "description": "used query filter.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "account id query filter.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "business id query filter.", "schema": { "type": "string" } }, { "name": "exclude_test", "in": "query", "required": false, "description": "exclude test query filter.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "date from query filter.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "date to query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List agent API keys response", "content": { "application/json": { "schema": { "type": "object", "description": "Masked, paginated agent-key ledger. Raw keys are never returned.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/agent-keys/{key_id}/revoke": { "post": { "tags": [ "Operations" ], "summary": "Revoke scoped agent API key", "description": "Revokes an agent API key. The raw key is never returned. Human AAL2 admin only; admin-agent keys cannot revoke agents or credentials.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" } } } }, "responses": { "200": { "description": "RevokeAgentApiKeyResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAgentApiKeyResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "key_id", "in": "path", "required": true, "description": "Agent API key id.", "schema": { "type": "string" } } ] } }, "/v1/admin/agent-billing-accounts": { "post": { "tags": [ "Operations" ], "summary": "Update agent billing account", "description": "Updates plan, billing status, included usage, and overage settings.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentBillingAccountRequest" } } } }, "responses": { "200": { "description": "UpdateAgentBillingAccountResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentBillingAccountResponse" } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/context": { "get": { "tags": [ "Customer Account" ], "summary": "Resolve signed-in account role", "description": "Returns the active role and workspace for the signature-verified human session, plus two-factor routing hints (is an authenticator enrolled; must this session step up before role endpoints answer). It exposes no account identifiers or PII and never weakens role-specific MFA gates — clients route on the hints, the role endpoints still enforce.", "security": [ { "SupabaseSessionBearer": [] } ], "responses": { "200": { "description": "Resolve signed-in account role response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "role", "status", "workspace", "role_exclusive", "mfa_enrolled", "step_up_required" ], "properties": { "schema_version": { "type": "string", "enum": [ "0.2" ] }, "role": { "type": [ "string", "null" ], "enum": [ "customer", "owner", "admin", null ] }, "status": { "type": "string", "enum": [ "active", "not_created" ] }, "workspace": { "type": "string", "enum": [ "customer", "owner", "admin", "none" ] }, "role_exclusive": { "type": "boolean", "const": true }, "mfa_enrolled": { "type": [ "boolean", "null" ] }, "step_up_required": { "type": [ "boolean", "null" ] } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/deletion-requests": { "post": { "tags": [ "Customer Account" ], "summary": "Request deletion of my customer account", "description": "This field follows the Loppee v3 Verified and Listed contract.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "confirmation", "acknowledge_data_effects" ], "properties": { "confirmation": { "type": "string", "enum": [ "DELETE MY LOPPEE ACCOUNT" ] }, "acknowledge_data_effects": { "type": "boolean", "const": true }, "reason": { "type": "string", "enum": [ "privacy", "no_longer_needed", "duplicate_account", "service_issue", "prefer_not_to_say" ] } } } } } }, "responses": { "200": { "description": "Request deletion of my customer account response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "request" ], "properties": { "status": { "type": "string", "enum": [ "requested", "already_pending" ] }, "request": { "type": "object", "additionalProperties": false, "required": [ "id", "account_role", "status", "reason", "requested_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "account_role": { "type": "string", "enum": [ "customer" ] }, "status": { "type": "string", "enum": [ "pending", "processing" ] }, "reason": { "type": "string", "enum": [ "privacy", "no_longer_needed", "duplicate_account", "service_issue", "prefer_not_to_say" ] }, "requested_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/mobile-devices/readiness": { "get": { "tags": [ "Customer Account" ], "summary": "Check customer mobile notification readiness", "description": "Reports whether server-owned Expo delivery is release-enabled. The response never exposes provider credentials or identifies which private gate is disabled.", "security": [ { "SupabaseCustomerBearer": [] } ], "responses": { "200": { "description": "Check customer mobile notification readiness response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "registration_supported", "delivery_enabled", "provider", "reason" ], "properties": { "status": { "type": "string", "enum": [ "ready", "disabled" ] }, "registration_supported": { "type": "boolean", "const": true }, "delivery_enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "expo" ] }, "reason": { "type": "string", "enum": [ "ready", "server_disabled" ] } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agent-location/readiness": { "get": { "tags": [ "Customer Account" ], "summary": "Check phone-to-assistant location readiness", "description": "Returns the signature-verified customer's coordinate-free device and App Attest readiness for one registered iPhone installation. Raw location, push tokens, agent keys, connection policy, and private gate details are never returned.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "installation_id", "in": "query", "required": true, "description": "The app installation UUID registered by this customer.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check phone-to-assistant location readiness response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "status", "available", "device_registered", "app_attest_registered", "completion_supported", "automatic_host_supported", "agent_receives_coordinates" ], "properties": { "schema_version": { "const": "agent-phone-location.v2" }, "status": { "type": "string", "enum": [ "ready", "disabled" ] }, "available": { "type": "boolean" }, "device_registered": { "type": "boolean" }, "app_attest_registered": { "type": "boolean" }, "completion_supported": { "type": "boolean" }, "automatic_host_supported": { "type": "boolean" }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agent-location/connections": { "get": { "tags": [ "Customer Account" ], "summary": "List iPhone location policies for my verified assistant connections", "description": "Returns every verified private assistant connection separately, including duplicate platforms, with its exact device-bound policy and last-use status. Platform names come only from the verified connection authority. The response never includes coordinates, an address, a device token, or an agent secret.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "installation_id", "in": "query", "required": true, "description": "The active Loppee iPhone installation UUID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List iPhone location policies for my verified assistant connections response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "device_registered", "all_paused", "connections", "app_attest_required", "agent_receives_coordinates" ], "properties": { "status": { "const": "ready" }, "device_registered": { "type": "boolean" }, "all_paused": { "type": "boolean" }, "connections": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "connection_id", "display_name", "platform_verified", "connection_label", "authentication_method", "oauth_grant_id", "policy", "policy_active", "server_authorized", "selected_at", "last_used_at", "last_use_mode", "connected_at", "automatic_request_proof", "automatic_host_supported" ], "properties": { "connection_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" }, "platform_verified": { "type": "boolean" }, "connection_label": { "type": [ "string", "null" ] }, "authentication_method": { "type": "string", "enum": [ "oauth", "api_key" ] }, "oauth_grant_id": { "type": [ "string", "null" ], "format": "uuid" }, "policy": { "type": "string", "enum": [ "always_allowed", "ask_every_time", "not_allowed" ] }, "policy_active": { "type": "boolean" }, "server_authorized": { "type": "boolean" }, "selected_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_use_mode": { "type": [ "string", "null" ], "enum": [ "automatic", "approved_in_app", null ] }, "connected_at": { "type": "string", "format": "date-time" }, "automatic_request_proof": { "const": "authenticated_connection_request" }, "automatic_host_supported": { "type": "boolean", "const": true } } } }, "app_attest_required": { "type": "boolean", "const": true }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agent-location/connections/{connection_id}/policy": { "post": { "tags": [ "Customer Account" ], "summary": "Set one verified assistant connection's iPhone location policy", "description": "Selects always_allowed, ask_every_time, or not_allowed for exactly one stable verified assistant connection and active Loppee iPhone installation. Enabling either location mode requires a one-use App Attest assertion from that exact iPhone; not_allowed remains an immediate bearer-authorized safety reduction. Always allowed still requires a trusted, replay-resistant host request receipt, and unsupported hosts fail closed to in-app approval.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "description": "connection id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "policy", "installation_id", "consent_copy_version" ], "properties": { "policy": { "const": "not_allowed" }, "installation_id": { "type": "string", "format": "uuid" }, "consent_copy_version": { "const": "agent-phone-location.v2" } } }, { "type": "object", "additionalProperties": false, "required": [ "policy", "installation_id", "consent_copy_version", "oauth_grant_id", "agent_key_id", "challenge_id", "challenge", "key_id", "assertion" ], "properties": { "policy": { "type": "string", "enum": [ "always_allowed", "ask_every_time" ] }, "installation_id": { "type": "string", "format": "uuid" }, "consent_copy_version": { "const": "agent-phone-location.v2" }, "oauth_grant_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_key_id": { "type": "string", "format": "uuid" }, "challenge_id": { "type": "string", "format": "uuid" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$" }, "assertion": { "type": "string", "maxLength": 349528 } } } ] } } } }, "responses": { "200": { "description": "Set one verified assistant connection's iPhone location policy response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "connection_id", "policy", "all_paused", "selected_at", "agent_receives_coordinates" ], "properties": { "status": { "const": "updated" }, "connection_id": { "type": "string", "format": "uuid" }, "policy": { "type": "string", "enum": [ "always_allowed", "ask_every_time", "not_allowed" ] }, "all_paused": { "type": "boolean" }, "selected_at": { "type": "string", "format": "date-time" }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agent-location/pause": { "post": { "tags": [ "Customer Account" ], "summary": "Pause or resume all assistant location access", "description": "Pauses or resumes the account-level assistant-location latch. Pausing is an immediate bearer-authorized safety reduction and invalidates pending current-location authority. Resuming requires a one-use App Attest assertion from the exact registered iPhone and does not change individual connection policies.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "paused" ], "properties": { "paused": { "type": "boolean", "const": true } } }, { "type": "object", "additionalProperties": false, "required": [ "paused", "installation_id", "consent_copy_version", "challenge_id", "challenge", "key_id", "assertion" ], "properties": { "paused": { "type": "boolean", "const": false }, "installation_id": { "type": "string", "format": "uuid" }, "consent_copy_version": { "const": "agent-phone-location.v2" }, "challenge_id": { "type": "string", "format": "uuid" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$" }, "assertion": { "type": "string", "maxLength": 349528 } } } ] } } } }, "responses": { "200": { "description": "Pause or resume all assistant location access response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "all_paused", "agent_receives_coordinates" ], "properties": { "status": { "type": "string", "enum": [ "paused", "active" ] }, "all_paused": { "type": "boolean" }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agent-location/activity": { "get": { "tags": [ "Customer Account" ], "summary": "List coordinate-free assistant location activity", "description": "Returns recent connection policy and one-shot use events without coordinates, addresses, device identifiers, tokens, prompts, or search text.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of events to return, from 1 through 50.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List coordinate-free assistant location activity response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "events", "coordinates_returned" ], "properties": { "status": { "const": "ready" }, "events": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "event_id", "connection_id", "display_name", "event_type", "policy", "created_at" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "event_type": { "type": "string", "enum": [ "policy_changed", "automatic_location_used", "approved_location_used", "all_paused", "all_resumed", "connection_revoked" ] }, "policy": { "type": [ "string", "null" ], "enum": [ "always_allowed", "ask_every_time", "not_allowed", null ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "coordinates_returned": { "type": "boolean", "const": false } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agent-location/app-attest/challenges": { "post": { "tags": [ "Customer Account" ], "summary": "Create an authenticated iPhone App Attest challenge", "description": "Issues a one-use App Attest challenge bound by the database to the signed-in customer and exact installation. Completion and authority_change challenges return only the server-derived account, user, connection or account action, current OAuth grant and agent key where applicable, handoff, mode, policy, and consent binding that the Loppee iPhone app must sign.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "X-Loppee-Client-Platform", "in": "header", "required": true, "description": "Must be ios; browser Fetch Metadata headers are rejected.", "schema": { "type": "string" } }, { "name": "X-Loppee-Installation-Id", "in": "header", "required": true, "description": "Must exactly match the signed-in customer's registered installation_id in the request body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "purpose", "installation_id", "key_id" ], "properties": { "purpose": { "const": "attestation" }, "installation_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 } } }, { "type": "object", "additionalProperties": false, "required": [ "purpose", "installation_id", "connection_id", "handoff_id", "use_mode", "key_id" ], "properties": { "purpose": { "const": "handoff_completion" }, "installation_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "handoff_id": { "type": "string", "format": "uuid" }, "use_mode": { "type": "string", "enum": [ "automatic", "approved_in_app" ] }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 } } }, { "type": "object", "additionalProperties": false, "required": [ "purpose", "installation_id", "action", "connection_id", "policy", "consent_copy_version", "key_id" ], "properties": { "purpose": { "const": "authority_change" }, "installation_id": { "type": "string", "format": "uuid" }, "action": { "const": "set_connection_policy" }, "connection_id": { "type": "string", "format": "uuid" }, "policy": { "type": "string", "enum": [ "always_allowed", "ask_every_time" ] }, "consent_copy_version": { "const": "agent-phone-location.v2" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 } } }, { "type": "object", "additionalProperties": false, "required": [ "purpose", "installation_id", "action", "consent_copy_version", "key_id" ], "properties": { "purpose": { "const": "authority_change" }, "installation_id": { "type": "string", "format": "uuid" }, "action": { "const": "resume_all" }, "consent_copy_version": { "const": "agent-phone-location.v2" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 } } }, { "type": "object", "additionalProperties": false, "required": [ "purpose", "installation_id", "action", "connection_id", "handoff_id", "key_id" ], "properties": { "purpose": { "const": "authority_change" }, "installation_id": { "type": "string", "format": "uuid" }, "action": { "const": "decline_handoff" }, "connection_id": { "type": "string", "format": "uuid" }, "handoff_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 } } } ] } } } }, "responses": { "200": { "description": "Create an authenticated iPhone App Attest challenge response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "challenge_id", "challenge", "purpose", "usable_until", "binding" ], "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "minLength": 43, "maxLength": 43 }, "purpose": { "type": "string", "enum": [ "attestation", "handoff_completion", "authority_change" ] }, "usable_until": { "type": "string", "format": "date-time" }, "binding": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "installation_id", "key_id" ], "properties": { "installation_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 } } }, { "type": "object", "additionalProperties": false, "required": [ "account_id", "auth_user_id", "installation_id", "connection_id", "oauth_grant_id", "agent_key_id", "handoff_id", "use_mode", "capture_source" ], "properties": { "account_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$", "minLength": 1, "maxLength": 128, "description": "Opaque Loppee customer service-account id; this is not assumed to be a UUID." }, "auth_user_id": { "type": "string", "format": "uuid" }, "installation_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "oauth_grant_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_key_id": { "type": "string", "format": "uuid" }, "handoff_id": { "type": "string", "format": "uuid" }, "use_mode": { "type": "string", "enum": [ "automatic", "approved_in_app" ] }, "capture_source": { "const": "loppee_ios_core_location" } } }, { "type": "object", "additionalProperties": false, "required": [ "account_id", "auth_user_id", "installation_id", "connection_id", "oauth_grant_id", "agent_key_id", "handoff_id", "request_mode", "action", "policy", "consent_copy_version" ], "properties": { "account_id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$", "minLength": 1, "maxLength": 128 }, "auth_user_id": { "type": "string", "format": "uuid" }, "installation_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": [ "string", "null" ], "format": "uuid" }, "oauth_grant_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "handoff_id": { "type": [ "string", "null" ], "format": "uuid" }, "request_mode": { "type": [ "string", "null" ], "enum": [ "automatic", "approval_required", null ] }, "action": { "type": "string", "enum": [ "set_connection_policy", "resume_all", "decline_handoff" ] }, "policy": { "type": [ "string", "null" ], "enum": [ "always_allowed", "ask_every_time", null ] }, "consent_copy_version": { "type": [ "string", "null" ], "enum": [ "agent-phone-location.v2", null ] } } } ] } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agent-location/app-attest/keys": { "post": { "tags": [ "Customer Account" ], "summary": "Register this signed-in iPhone's App Attest key", "description": "Verifies Apple's attestation for the allowlisted Loppee iPhone app and atomically binds the key to the authenticated customer and exact registered installation. Browser, desktop, agent-key, and extensionless requests outside the explicit release policy are rejected.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "X-Loppee-Client-Platform", "in": "header", "required": true, "description": "Must be ios; browser Fetch Metadata headers are rejected.", "schema": { "type": "string" } }, { "name": "X-Loppee-Installation-Id", "in": "header", "required": true, "description": "Must exactly match the signed-in customer's registered installation_id in the request body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "challenge_id", "challenge", "installation_id", "key_id", "attestation" ], "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "installation_id": { "type": "string", "format": "uuid" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 }, "attestation": { "type": "string", "maxLength": 349528 } } } } } }, "responses": { "200": { "description": "Register this signed-in iPhone's App Attest key response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "environment", "app_attest_registered" ], "properties": { "status": { "const": "registered" }, "environment": { "type": "string", "enum": [ "production", "development" ] }, "app_attest_registered": { "type": "boolean", "const": true } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/location-handoffs/pending": { "get": { "tags": [ "Customer Account" ], "summary": "List actionable assistant location requests for this iPhone", "description": "Returns at most ten unexpired current-location request ids for the signature-verified customer, exact active iPhone installation, authorization, and assistant key. This in-app recovery list is coordinate-free and exposes no account, device, push, authorization, browser-token, or agent-key identifier.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "installation_id", "in": "query", "required": true, "description": "The app installation UUID registered by this customer.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List actionable assistant location requests for this iPhone response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "requests", "agent_receives_coordinates" ], "properties": { "status": { "const": "ready" }, "requests": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "handoff_id", "status", "approval_expires_at", "connection_id", "display_name", "request_mode" ], "properties": { "handoff_id": { "type": "string", "format": "uuid" }, "status": { "const": "awaiting_customer" }, "approval_expires_at": { "type": "string", "format": "date-time" }, "connection_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "request_mode": { "type": "string", "enum": [ "automatic", "approval_required" ] } } } }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/location-handoffs/{handoff_id}/device-readiness": { "get": { "tags": [ "Customer Account" ], "summary": "Check whether an assistant location request is actionable on this phone", "description": "Revalidates the signed-in customer, registered installation, active authorization, exact assistant key, and unexpired awaiting request before the native app asks iOS for a location. The response is coordinate-free.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "handoff_id", "in": "path", "required": true, "description": "handoff id path identifier.", "schema": { "type": "string" } }, { "name": "installation_id", "in": "query", "required": true, "description": "The app installation UUID registered by this customer.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Check whether an assistant location request is actionable on this phone response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "handoff_id", "status", "actionable", "connection_id", "request_mode", "automatic_host_supported", "agent_receives_coordinates" ], "properties": { "handoff_id": { "type": "string", "format": "uuid" }, "status": { "const": "awaiting_customer" }, "actionable": { "type": "boolean", "const": true }, "connection_id": { "type": "string", "format": "uuid" }, "request_mode": { "type": "string", "enum": [ "automatic", "approval_required" ] }, "automatic_host_supported": { "type": "boolean" }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/location-handoffs/{handoff_id}/decline-from-device": { "post": { "tags": [ "Customer Account" ], "summary": "Decline an assistant location request from the customer's phone", "description": "Requires the signed-in, originless Loppee iOS client plus a one-use App Attest assertion over the exact active installation, verified assistant connection, current credential, handoff, and request mode. It invalidates the request, suppresses pending delivery, clears encrypted coordinate material, and never accepts or returns coordinates.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "handoff_id", "in": "path", "required": true, "description": "handoff id path identifier.", "schema": { "type": "string" } }, { "name": "X-Loppee-Client-Platform", "in": "header", "required": true, "description": "Must be ios; browser Fetch Metadata headers are rejected.", "schema": { "type": "string" } }, { "name": "X-Loppee-Installation-Id", "in": "header", "required": true, "description": "Must exactly match the signed-in customer's registered installation_id in the request body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "installation_id", "connection_id", "oauth_grant_id", "agent_key_id", "request_mode", "challenge_id", "challenge", "key_id", "assertion" ], "properties": { "installation_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "oauth_grant_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_key_id": { "type": "string", "format": "uuid" }, "request_mode": { "type": "string", "enum": [ "automatic", "approval_required" ] }, "challenge_id": { "type": "string", "format": "uuid" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 }, "assertion": { "type": "string", "maxLength": 349528 } } } } } }, "responses": { "200": { "description": "Decline an assistant location request from the customer's phone response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "handoff_id", "status", "declined", "agent_receives_coordinates" ], "properties": { "handoff_id": { "type": "string", "format": "uuid" }, "status": { "const": "declined" }, "declined": { "type": "boolean", "const": true }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/location-handoffs/{handoff_id}/complete-from-device": { "post": { "tags": [ "Customer Account" ], "summary": "Complete an assistant location request from the customer's phone", "description": "Requires an App Attest assertion over the server-derived account, user, installation, stable connection, OAuth grant, active agent key, handoff, use mode, challenge, and Loppee iOS Core Location capture. It atomically consumes one sign counter and completes one use only. Bearer plus installation UUID alone is insufficient; the response never returns coordinates.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "handoff_id", "in": "path", "required": true, "description": "handoff id path identifier.", "schema": { "type": "string" } }, { "name": "X-Loppee-Client-Platform", "in": "header", "required": true, "description": "Must be ios; browser Fetch Metadata headers are rejected.", "schema": { "type": "string" } }, { "name": "X-Loppee-Installation-Id", "in": "header", "required": true, "description": "Must exactly match the signed-in customer's registered installation_id in the request body.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "installation_id", "connection_id", "oauth_grant_id", "agent_key_id", "use_mode", "capture_source", "challenge_id", "challenge", "key_id", "assertion", "latitude", "longitude", "accuracy_meters", "captured_at" ], "properties": { "installation_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "oauth_grant_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_key_id": { "type": "string", "format": "uuid" }, "use_mode": { "type": "string", "enum": [ "automatic", "approved_in_app" ] }, "capture_source": { "const": "loppee_ios_core_location" }, "challenge_id": { "type": "string", "format": "uuid" }, "challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "key_id": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$", "minLength": 44, "maxLength": 44 }, "assertion": { "type": "string", "maxLength": 349528 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_meters": { "type": "number", "exclusiveMinimum": 0, "maximum": 500 }, "captured_at": { "type": "string", "format": "date-time" } } } } } }, "responses": { "200": { "description": "Complete an assistant location request from the customer's phone response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "handoff_id", "status", "completed", "use_mode", "agent_receives_coordinates" ], "properties": { "handoff_id": { "type": "string", "format": "uuid" }, "status": { "const": "ready" }, "completed": { "type": "boolean", "const": true }, "use_mode": { "type": "string", "enum": [ "automatic", "approved_in_app" ] }, "agent_receives_coordinates": { "type": "boolean", "const": false } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/mobile-devices": { "post": { "tags": [ "Customer Account" ], "summary": "Register this customer mobile installation for push delivery", "description": "Stores one private Expo push token for the signature-verified customer installation. The token is never returned, audited, or exposed publicly.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "installation_id", "platform", "push_token" ], "properties": { "installation_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "push_token": { "type": "string", "pattern": "^Expo(?:nent)?PushToken\\[[A-Za-z0-9_-]{20,256}\\]$", "minLength": 35, "maxLength": 280 } } } } } }, "responses": { "200": { "description": "Register this customer mobile installation for push delivery response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "device" ], "properties": { "status": { "type": "string", "enum": [ "registered" ] }, "device": { "type": "object", "additionalProperties": false, "required": [ "installation_id", "platform", "status", "registered_at" ], "properties": { "installation_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "status": { "type": "string", "enum": [ "active" ] }, "registered_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/mobile-devices/revoke": { "post": { "tags": [ "Customer Account" ], "summary": "Revoke this customer mobile installation", "description": "Revoke this customer mobile installation. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "installation_id" ], "properties": { "installation_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Revoke this customer mobile installation response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "installation_id" ], "properties": { "status": { "type": "string", "enum": [ "revoked" ] }, "installation_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/account": { "get": { "tags": [ "Business Owner" ], "summary": "Get owner account status", "description": "Get owner account status. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "responses": { "200": { "description": "Get owner account status response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner account state.", "additionalProperties": true, "required": [ "status", "user_id", "email", "owner_account", "customer_conflict", "admin_conflict" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Business Owner" ], "summary": "Create or update owner account", "description": "Create or update owner account. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "full_name": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Create or update owner account response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner account state.", "additionalProperties": true, "required": [ "status", "owner_account" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/deletion-requests": { "post": { "tags": [ "Business Owner" ], "summary": "Request deletion of my business-owner account", "description": "Requires a fresh AAL2 owner session and starts an auditable, non-destructive privacy-operations workflow. It never deletes an owner, business, review, evidence item, or auth identity inline.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "confirmation", "acknowledge_data_effects", "reason" ], "properties": { "confirmation": { "type": "string", "enum": [ "DELETE MY LOPPEE BUSINESS ACCOUNT" ] }, "acknowledge_data_effects": { "type": "boolean", "const": true }, "reason": { "type": "string", "enum": [ "privacy", "no_longer_needed", "duplicate_account", "service_issue", "prefer_not_to_say" ] } } } } } }, "responses": { "200": { "description": "Request deletion of my business-owner account response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "request" ], "properties": { "status": { "type": "string", "enum": [ "requested", "already_pending" ] }, "request": { "type": "object", "additionalProperties": false, "required": [ "id", "account_role", "status", "reason", "requested_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "account_role": { "type": "string", "enum": [ "owner" ] }, "status": { "type": "string", "enum": [ "pending", "processing" ] }, "reason": { "type": "string", "enum": [ "privacy", "no_longer_needed", "duplicate_account", "service_issue", "prefer_not_to_say" ] }, "requested_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mobile-devices/readiness": { "get": { "tags": [ "Business Owner" ], "summary": "Check owner mobile notification readiness", "description": "Reports whether server-owned Expo delivery is release-enabled. The response never exposes provider credentials or identifies which private gate is disabled.", "security": [ { "SupabaseOwnerBearer": [] } ], "responses": { "200": { "description": "Check owner mobile notification readiness response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "registration_supported", "delivery_enabled", "provider", "reason" ], "properties": { "status": { "type": "string", "enum": [ "ready", "disabled" ] }, "registration_supported": { "type": "boolean", "const": true }, "delivery_enabled": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "expo" ] }, "reason": { "type": "string", "enum": [ "ready", "server_disabled" ] } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mobile-devices": { "post": { "tags": [ "Business Owner" ], "summary": "Register this owner mobile installation for push delivery", "description": "Stores one private Expo push token for the signature-verified owner installation. The token is never returned, audited, or exposed publicly.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "installation_id", "platform", "push_token" ], "properties": { "installation_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "push_token": { "type": "string", "pattern": "^Expo(?:nent)?PushToken\\[[A-Za-z0-9_-]{20,256}\\]$", "minLength": 35, "maxLength": 280 } } } } } }, "responses": { "200": { "description": "Register this owner mobile installation for push delivery response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "device" ], "properties": { "status": { "type": "string", "enum": [ "registered" ] }, "device": { "type": "object", "additionalProperties": false, "required": [ "installation_id", "platform", "status", "registered_at" ], "properties": { "installation_id": { "type": "string", "format": "uuid" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "status": { "type": "string", "enum": [ "active" ] }, "registered_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/mobile-devices/revoke": { "post": { "tags": [ "Business Owner" ], "summary": "Revoke this owner mobile installation", "description": "Revoke this owner mobile installation. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "installation_id" ], "properties": { "installation_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Revoke this owner mobile installation response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "installation_id" ], "properties": { "status": { "type": "string", "enum": [ "revoked" ] }, "installation_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/conversations": { "get": { "tags": [ "Business Owner" ], "summary": "List owner conversations", "description": "List owner conversations. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "responses": { "200": { "description": "List owner conversations response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner-scoped customer conversations and reply turns.", "additionalProperties": true, "required": [ "schema_version", "generated_at", "serviceInteractions", "messageReplies" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/conversations/{conversation_id}/read": { "post": { "tags": [ "Business Owner" ], "summary": "Mark owner conversation read", "description": "Mark owner conversation read. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mark owner conversation read response", "content": { "application/json": { "schema": { "type": "object", "description": "Durable read acknowledgement.", "additionalProperties": true, "required": [ "status", "conversation_id", "read_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/evidence/authorize": { "post": { "tags": [ "Business Owner" ], "summary": "Authorize a business evidence upload", "description": "Runs the owner-membership and recent-security-confirmation gates before the private document body is read. The upload endpoint repeats the same authorization checks.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id" ], "properties": { "business_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Authorize a business evidence upload response", "content": { "application/json": { "schema": { "type": "object", "description": "Short-lived evidence-upload preflight acknowledgement.", "additionalProperties": true, "required": [ "status", "business_id", "expires_in_seconds" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/evidence/upload-intents": { "post": { "tags": [ "Business Owner" ], "summary": "Create a private evidence upload intent", "description": "Binds one short-lived private upload to the authenticated owner, business, factor, MIME type, byte length, and SHA-256. The upload token is returned once and only its digest is stored.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id", "factor_id", "kind", "file_name", "content_type", "size_bytes", "file_sha256", "issuer", "credential_identifier" ], "properties": { "business_id": { "type": "string" }, "factor_id": { "type": "string", "enum": [ "insurance", "identity_ownership", "license", "domain_ownership", "phone_reachability" ] }, "kind": { "type": "string", "enum": [ "insurance_document", "source_screenshot" ] }, "file_name": { "type": "string" }, "content_type": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png", "image/webp" ] }, "size_bytes": { "type": "number", "minimum": 1, "maximum": 8388608 }, "file_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "issuer": { "type": "string" }, "credential_identifier": { "type": "string" }, "jurisdiction": { "type": "string" }, "evidence_observed_at": { "type": "string" }, "expires_at": { "type": "string" }, "source_url": { "type": "string" } } } } } }, "responses": { "200": { "description": "Create a private evidence upload intent response", "content": { "application/json": { "schema": { "type": "object", "description": "Short-lived exact-file upload authority.", "additionalProperties": true, "required": [ "status", "business_id", "factor_id", "intent_id", "upload_url", "upload_token", "upload_method", "required_content_type", "required_size_bytes", "expires_at", "finalize_url", "malware_scan_status" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/evidence/upload-intents/{intent_id}/object": { "put": { "tags": [ "Business Owner" ], "summary": "Upload the exact private evidence object", "description": "Accepts raw PDF or image bytes authorized by both the authenticated AAL2 owner session and the X-Loppee-Upload-Token header. The owner, token, content type, size, SHA-256, and file signature must all match the immutable intent. A private asynchronous safety scan begins before the evidence can enter review.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "intent_id", "in": "path", "required": true, "description": "intent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload the exact private evidence object response", "content": { "application/json": { "schema": { "type": "object", "description": "Private object upload receipt.", "additionalProperties": true, "required": [ "status", "intent_id", "factor_id", "size_bytes", "file_sha256", "finalize_by" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/internal/owner-evidence/scan-results": { "post": { "tags": [ "Moderated Actions" ], "summary": "Record a private evidence scan result", "description": "Render Workflow callback bound to one upload intent by a secret header. Clean files finalize automatically; unsafe files are quarantined.", "security": [ { "OwnerEvidenceScanCallback": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "intent_id", "result", "scanner", "scanner_version", "file_sha256" ], "properties": { "intent_id": { "type": "string" }, "result": { "type": "string", "enum": [ "clean", "infected", "error" ] }, "scanner": { "type": "string", "enum": [ "clamav" ] }, "scanner_version": { "type": "string" }, "file_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" } } } } } }, "responses": { "200": { "description": "Record a private evidence scan result response", "content": { "application/json": { "schema": { "type": "object", "description": "Finalized evidence or quarantine receipt.", "additionalProperties": true, "required": [ "status" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/internal/jobs/resume-scan-results": { "post": { "tags": [ "Moderated Actions" ], "summary": "Record a private job-resume scan result", "description": "Private Render Workflow callback bound to one immutable resume-upload intent by a dedicated per-intent secret header plus the exact scan authority, SHA-256, content type, and byte size. It is not an agent or public endpoint.", "security": [ { "JobResumeScanCallback": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "intent_id", "scan_authority_id", "result", "scanner", "scanner_version", "file_sha256", "content_type", "size_bytes" ], "properties": { "intent_id": { "type": "string", "pattern": "^jrui_[0-9a-fA-F-]{36}$" }, "scan_authority_id": { "type": "string", "format": "uuid" }, "result": { "type": "string", "enum": [ "clean", "infected", "error" ] }, "scanner": { "type": "string", "enum": [ "clamav" ] }, "scanner_version": { "type": "string", "minLength": 1, "maxLength": 160 }, "file_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "content_type": { "type": "string", "enum": [ "application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ] }, "size_bytes": { "type": "number", "minimum": 1, "maximum": 5242880 }, "signature": { "type": "string", "maxLength": 256 } } } } } }, "responses": { "200": { "description": "Record a private job-resume scan result response", "content": { "application/json": { "schema": { "type": "object", "description": "Bound resume-scan completion receipt.", "additionalProperties": true, "required": [ "status", "intent_id", "application_id", "scan_status" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/evidence/upload-intents/{intent_id}/finalize": { "post": { "tags": [ "Business Owner" ], "summary": "Finalize a private evidence upload", "description": "Rechecks owner membership and recent security confirmation, then records the existing owner-provided or pending-review receipt. Uploading never approves verification.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "intent_id", "in": "path", "required": true, "description": "intent id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id" ], "properties": { "business_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Finalize a private evidence upload response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner-provided or pending-review evidence receipt.", "additionalProperties": true, "required": [ "status", "business_id", "factor_id", "created_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/evidence": { "post": { "tags": [ "Business Owner" ], "summary": "Submit business evidence", "description": "Submit business evidence. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id", "kind", "file_name", "content_type", "size_bytes", "data_base64" ], "properties": { "business_id": { "type": "string" }, "kind": { "type": "string" }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number", "minimum": 0 }, "data_base64": { "type": "string" }, "file_sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" }, "factor_id": { "type": "string", "enum": [ "identity_ownership", "license", "insurance" ] }, "submitted_identifier": { "type": "string" }, "jurisdiction": { "type": "string" }, "carrier_name": { "type": "string" }, "policy_number": { "type": "string" }, "stated_expires_at": { "type": "string" }, "evidence_observed_at": { "type": "string" } } } } } }, "responses": { "200": { "description": "Submit business evidence response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner evidence result. In v3, entity/license documents return a private pending manual-verification submission; insurance returns owner-provided metadata with no verification effect. Legacy v2 submissions retain their existing asset response.", "additionalProperties": true, "required": [ "status", "business_id", "created_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/photos": { "post": { "tags": [ "Business Owner" ], "summary": "Upload business photo", "description": "Upload business photo. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "kind", "file_name", "content_type", "size_bytes", "data_base64" ], "properties": { "business_id": { "type": "string" }, "kind": { "type": "string" }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number", "minimum": 0 }, "data_base64": { "type": "string" } } } } } }, "responses": { "200": { "description": "Upload business photo response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner media upload result.", "additionalProperties": true, "required": [ "status", "business_id", "asset", "created_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/photos/remove": { "post": { "tags": [ "Business Owner" ], "summary": "Remove business photo", "description": "Remove business photo. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "asset_id" ], "properties": { "business_id": { "type": "string" }, "asset_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Remove business photo response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner media removal result.", "additionalProperties": true, "required": [ "status", "business_id", "asset_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/profile-details": { "post": { "tags": [ "Business Owner" ], "summary": "Edit owner business display details", "description": "Edit owner business display details. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id", "expected_updated_at", "display_name", "phone", "website" ], "properties": { "business_id": { "type": "string" }, "expected_updated_at": { "type": "string" }, "display_name": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" } } } } } }, "responses": { "200": { "description": "Edit owner business display details response", "content": { "application/json": { "schema": { "type": "object", "description": "Versioned display-details receipt. Never grants ownership or verification.", "additionalProperties": true, "required": [ "status", "business_id", "updated_at", "fields" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/hours": { "post": { "tags": [ "Business Owner" ], "summary": "Set structured business hours", "description": "Set structured business hours. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "business_id": { "type": "string" }, "hours": { "type": [ "object", "null" ], "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Set structured business hours response", "content": { "application/json": { "schema": { "type": "object", "description": "Structured-hours update result.", "additionalProperties": true, "required": [ "status", "business_id", "hours", "time_zone", "open_now" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/category-requests": { "post": { "tags": [ "Business Owner" ], "summary": "Request an additional business category", "description": "Request an additional business category. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "category_aliases", "license_number" ], "properties": { "business_id": { "type": "string" }, "category_aliases": { "type": "array", "items": { "type": "string" } }, "license_number": { "type": "string" }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Request an additional business category response", "content": { "application/json": { "schema": { "type": "object", "description": "Pending category request. Nothing changes publicly before admin review.", "additionalProperties": true, "required": [ "status", "request" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/billing/checkout": { "post": { "tags": [ "Business Owner" ], "summary": "Create owner billing checkout", "description": "Create owner billing checkout. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "tier" ], "properties": { "business_id": { "type": "string" }, "tier": { "type": "string" }, "period": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Create owner billing checkout response", "content": { "application/json": { "schema": { "type": "object", "description": "Billing checkout session.", "additionalProperties": true, "required": [ "url", "tier", "period", "business_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/billing/portal": { "post": { "tags": [ "Business Owner" ], "summary": "Create owner billing portal session", "description": "Create owner billing portal session. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "business_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Create owner billing portal session response", "content": { "application/json": { "schema": { "type": "object", "description": "Billing portal session.", "additionalProperties": true, "required": [ "url", "business_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/exposure-tier": { "post": { "tags": [ "Business Owner" ], "summary": "Select an exposure tier", "description": "Select an exposure tier. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "tier" ], "properties": { "business_id": { "type": "string" }, "tier": { "type": "string" }, "period": { "type": "string", "enum": [ "monthly", "annual" ] }, "coupon_code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Select an exposure tier response", "content": { "application/json": { "schema": { "type": "object", "description": "Exposure selection or checkout result. Payment may affect discovery reach, gallery capacity, and labeled sponsorship only.", "additionalProperties": true, "required": [ "status", "tier", "business_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/diamond-radius": { "post": { "tags": [ "Business Owner" ], "summary": "Purchase or update Diamond discovery radius", "description": "Purchase or update Diamond discovery radius. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "radius_miles" ], "properties": { "business_id": { "type": "string" }, "radius_miles": { "type": "number", "minimum": 30, "maximum": 50 }, "period": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Purchase or update Diamond discovery radius response", "content": { "application/json": { "schema": { "type": "object", "description": "Diamond reach checkout or update result. Reach affects discovery eligibility only.", "additionalProperties": true, "required": [ "status", "radius_miles", "business_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/locations": { "get": { "tags": [ "Business Owner" ], "summary": "List owner business locations", "description": "List owner business locations. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": false, "description": "business id query filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List owner business locations response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner-scoped business locations.", "additionalProperties": true, "required": [ "business_id", "exposure_tier", "online_billing_live", "branch_addon_options", "locations" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Business Owner" ], "summary": "Create business location", "description": "Create business location. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "street_address", "city", "state", "radius_miles" ], "properties": { "business_id": { "type": "string" }, "label": { "type": "string" }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "service_areas": { "type": "string" }, "radius_miles": { "type": "number", "enum": [ 5, 10, 20, 30 ] }, "period": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Create business location response", "content": { "application/json": { "schema": { "type": "object", "description": "Created location and any billing checkout state.", "additionalProperties": true, "required": [ "status" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/locations/{location_id}/delete": { "post": { "tags": [ "Business Owner" ], "summary": "Delete business location", "description": "Delete business location. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "location_id", "in": "path", "required": true, "description": "location id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "business_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Delete business location response", "content": { "application/json": { "schema": { "type": "object", "description": "Location deletion result.", "additionalProperties": true, "required": [ "status", "id", "locations" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/locations/{location_id}": { "post": { "tags": [ "Business Owner" ], "summary": "Update business location", "description": "Update business location. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "location_id", "in": "path", "required": true, "description": "location id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "business_id": { "type": "string" }, "label": { "type": "string" }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "service_areas": { "type": "string" } } } } } }, "responses": { "200": { "description": "Update business location response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated location.", "additionalProperties": true, "required": [ "status", "location" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/deals": { "post": { "tags": [ "Business Owner" ], "summary": "Create business deal", "description": "Create business deal. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id", "title", "discount_label" ], "properties": { "business_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "discount_label": { "type": "string" }, "promo_code": { "type": [ "string", "null" ] }, "terms": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Create business deal response", "content": { "application/json": { "schema": { "type": "object", "description": "Created owner deal.", "additionalProperties": true, "required": [ "status", "deal" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/deals/{deal_id}/delete": { "post": { "tags": [ "Business Owner" ], "summary": "Delete business deal", "description": "Delete business deal. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "deal id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete business deal response", "content": { "application/json": { "schema": { "type": "object", "description": "Deal deletion result.", "additionalProperties": true, "required": [ "status", "id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/deals/{deal_id}": { "post": { "tags": [ "Business Owner" ], "summary": "Update business deal", "description": "Update business deal. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "deal id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "discount_label": { "type": "string" }, "promo_code": { "type": [ "string", "null" ] }, "terms": { "type": [ "string", "null" ] }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Update business deal response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated owner deal.", "additionalProperties": true, "required": [ "status", "deal" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/jobs": { "post": { "tags": [ "Business Owner" ], "summary": "Create job posting", "description": "Create job posting. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id", "title" ], "properties": { "business_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "temporary", "internship", "seasonal" ] }, "workplace_type": { "type": "string", "enum": [ "on_site", "hybrid", "remote" ] }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "category_alias": { "type": "string" }, "compensation_text": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } }, "experience_level": { "type": "string" }, "salary_min": { "type": [ "number", "null" ], "minimum": 0 }, "salary_max": { "type": [ "number", "null" ], "minimum": 0 }, "salary_currency": { "type": "string" }, "salary_period": { "type": "string", "enum": [ "", "hourly", "monthly", "yearly" ] }, "benefits": { "type": "string" }, "schedule": { "type": "string" }, "applicant_location_requirements": { "type": "string" }, "total_job_openings": { "type": [ "integer", "null" ], "minimum": 1 }, "direct_apply": { "type": "boolean" }, "apply_url": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "filled", "closed" ] } } } } } }, "responses": { "200": { "description": "Create job posting response", "content": { "application/json": { "schema": { "type": "object", "description": "Created job posting.", "additionalProperties": true, "required": [ "status", "job", "pricing" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/jobs/{job_id}/delete": { "post": { "tags": [ "Business Owner" ], "summary": "Delete job posting", "description": "Delete job posting. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete job posting response", "content": { "application/json": { "schema": { "type": "object", "description": "Job deletion result.", "additionalProperties": true, "required": [ "status", "id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/jobs/{job_id}/checkout": { "post": { "tags": [ "Business Owner" ], "summary": "Create job-posting checkout", "description": "Create job-posting checkout. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Create job-posting checkout response", "content": { "application/json": { "schema": { "type": "object", "description": "Job-posting checkout session.", "additionalProperties": true, "required": [ "status", "job", "pricing" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/jobs/{job_id}": { "post": { "tags": [ "Business Owner" ], "summary": "Update job posting", "description": "Update job posting. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "temporary", "internship", "seasonal" ] }, "workplace_type": { "type": "string", "enum": [ "on_site", "hybrid", "remote" ] }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "category_alias": { "type": "string" }, "compensation_text": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } }, "experience_level": { "type": "string" }, "salary_min": { "type": [ "number", "null" ], "minimum": 0 }, "salary_max": { "type": [ "number", "null" ], "minimum": 0 }, "salary_currency": { "type": "string" }, "salary_period": { "type": "string", "enum": [ "", "hourly", "monthly", "yearly" ] }, "benefits": { "type": "string" }, "schedule": { "type": "string" }, "applicant_location_requirements": { "type": "string" }, "total_job_openings": { "type": [ "integer", "null" ], "minimum": 1 }, "direct_apply": { "type": "boolean" }, "apply_url": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "filled", "closed" ] } } } } } }, "responses": { "200": { "description": "Update job posting response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated job posting.", "additionalProperties": true, "required": [ "status", "job", "pricing" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents": { "post": { "tags": [ "Business Owner" ], "summary": "Connect business-management agent", "description": "Connect one owner-supplied external management agent with an explicit least-privilege action scope. Omitted, empty, duplicate, or unknown actions are rejected; Loppee never infers full access. The human owner and recent-second-factor gates remain authoritative.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "business_id", "name", "actions" ], "properties": { "business_id": { "type": "string" }, "name": { "type": "string" }, "actions": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "manage_deals", "update_business_profile", "update_business_photos", "list_customer_messages", "reply_to_customer_message", "list_support_messages", "send_support_message", "list_notifications", "mark_notification_read", "list_missed_contacts", "respond_to_review", "report_review", "manage_job_posting", "validate_coupon", "redeem_coupon", "list_job_applications", "update_job_application_status" ] } } } } } } }, "responses": { "200": { "description": "Connect business-management agent response", "content": { "application/json": { "schema": { "type": "object", "description": "Connected management agent; raw key is returned once.", "additionalProperties": true, "required": [ "status", "external_agent_access", "agent", "key", "raw_key", "one_time_display", "mcp_endpoint" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents/{agent_id}/rotate-key": { "post": { "tags": [ "Business Owner" ], "summary": "Rotate business-management agent key", "description": "Rotate business-management agent key. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate business-management agent key response", "content": { "application/json": { "schema": { "type": "object", "description": "Rotated management-agent key; raw key is returned once.", "additionalProperties": true, "required": [ "status", "external_agent_access", "agent", "key", "raw_key", "one_time_display", "mcp_endpoint" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents/{agent_id}/permissions": { "post": { "tags": [ "Business Owner" ], "summary": "Update business-management agent permissions", "description": "Human-owner-only step-up scope replacement for the one active key belonging to an owner-managed business agent. The supplied actions replace, rather than merge with, the key's explicit allowed_actions. Agent API keys and MCP tools cannot call this authority endpoint.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "actions" ], "properties": { "actions": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "manage_deals", "update_business_profile", "update_business_photos", "list_customer_messages", "reply_to_customer_message", "list_support_messages", "send_support_message", "list_notifications", "mark_notification_read", "list_missed_contacts", "respond_to_review", "report_review", "manage_job_posting", "validate_coupon", "redeem_coupon", "list_job_applications", "update_job_application_status" ] } } } } } } }, "responses": { "200": { "description": "Update business-management agent permissions response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "agent" ], "properties": { "status": { "type": "string", "enum": [ "permissions_updated" ] }, "agent": { "type": "object", "additionalProperties": false, "required": [ "account_id", "name", "business_id", "allowed_actions" ], "properties": { "account_id": { "type": "string" }, "name": { "type": "string" }, "business_id": { "type": "string" }, "allowed_actions": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "manage_deals", "update_business_profile", "update_business_photos", "list_customer_messages", "reply_to_customer_message", "list_support_messages", "send_support_message", "list_notifications", "mark_notification_read", "list_missed_contacts", "respond_to_review", "report_review", "manage_job_posting", "validate_coupon", "redeem_coupon", "list_job_applications", "update_job_application_status" ] } } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents/{agent_id}/disconnect": { "post": { "tags": [ "Business Owner" ], "summary": "Disconnect business-management agent", "description": "Disconnect business-management agent. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disconnect business-management agent response", "content": { "application/json": { "schema": { "type": "object", "description": "Agent disconnection and key-revocation result.", "additionalProperties": true, "required": [ "status", "account_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents/{agent_id}/webhook": { "get": { "tags": [ "Business Owner" ], "summary": "Get business-management agent webhook", "description": "Returns the signed HTTPS wake-up endpoint for this owner-managed external agent. The response never reveals the one-time signing secret or the agent API key.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get business-management agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Business Owner" ], "summary": "Register business-management agent webhook", "description": "Human-owner-only recent-AAL2 registration of a provider-neutral HTTPS wake-up receiver for the one active management-agent credential. Loppee sends reference-only customer.message.created events; the receiver verifies the HMAC and uses its separately scoped Loppee API/MCP key to read or act. Re-registering replaces the endpoint and rotates the signing secret, which is returned once.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048, "description": "Public HTTPS receiver operated by the connecting principal or its agent runtime. Credentials in the URL and private-network destinations are rejected." } } } } } }, "responses": { "200": { "description": "Register business-management agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint", "signing_secret", "one_time_display", "delivery_contract" ], "properties": { "status": { "type": "string", "enum": [ "registered", "rotated" ] }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "signing_secret": { "type": "string", "pattern": "^loppee_whsec_", "minLength": 32 }, "one_time_display": { "const": true }, "delivery_contract": { "type": "object", "additionalProperties": false, "required": [ "version", "authentication", "payload_mode" ], "properties": { "version": { "const": "loppee.webhook.v1" }, "authentication": { "const": "hmac_sha256" }, "payload_mode": { "const": "reference_only" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents/{agent_id}/webhook/rotate-secret": { "post": { "tags": [ "Business Owner" ], "summary": "Rotate business-management agent webhook secret", "description": "Human-owner-only recent-AAL2 rotation of the HMAC signing secret. The replacement secret is returned once; the scoped Loppee API/MCP key is separate and unchanged.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate business-management agent webhook secret response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint", "signing_secret", "one_time_display", "delivery_contract" ], "properties": { "status": { "type": "string", "enum": [ "registered", "rotated" ] }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "signing_secret": { "type": "string", "pattern": "^loppee_whsec_", "minLength": 32 }, "one_time_display": { "const": true }, "delivery_contract": { "type": "object", "additionalProperties": false, "required": [ "version", "authentication", "payload_mode" ], "properties": { "version": { "const": "loppee.webhook.v1" }, "authentication": { "const": "hmac_sha256" }, "payload_mode": { "const": "reference_only" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents/{agent_id}/webhook/disable": { "post": { "tags": [ "Business Owner" ], "summary": "Disable business-management agent webhook", "description": "Human-owner-only recent-AAL2 disablement of wake-up deliveries for this management agent. Disabling the webhook does not broaden, replace, or reveal the agent's scoped Loppee API/MCP key.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disable business-management agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint" ], "properties": { "status": { "const": "disabled" }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/agents/{agent_id}/webhook/test": { "post": { "tags": [ "Business Owner" ], "summary": "Test business-management agent webhook", "description": "Human-owner-only recent-AAL2 enqueue of a signed agent.webhook.test wake-up event. It uses the live signing and delivery path, but is receipt-only: the receiver validates the signature/timestamp and returns 2xx without fetching a resource.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test business-management agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "event_id", "endpoint_id" ], "properties": { "status": { "const": "queued" }, "event_id": { "type": "string" }, "endpoint_id": { "type": "string" } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/missed-contacts": { "get": { "tags": [ "Business Owner" ], "summary": "List missed Loppee contacts", "description": "List missed Loppee contacts. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "business_id", "in": "query", "required": true, "description": "business id query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List missed Loppee contacts response", "content": { "application/json": { "schema": { "type": "object", "description": "Tier-aware missed-contact view. Free-tier responses remain redacted.", "additionalProperties": true, "required": [ "schema_version", "business_id", "model_active", "locked", "total_count", "attempts" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/missed-contacts/convert": { "post": { "tags": [ "Business Owner" ], "summary": "Convert missed contact to conversation", "description": "Convert missed contact to conversation. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "business_id", "attempt_id" ], "properties": { "business_id": { "type": "string" }, "attempt_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Convert missed contact to conversation response", "content": { "application/json": { "schema": { "type": "object", "description": "Missed-contact conversion result.", "additionalProperties": true, "required": [ "status", "attempt_id", "interaction_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/messages/{interaction_id}/agent-drafts": { "get": { "tags": [ "Business Owner" ], "summary": "List owner-reviewed agent reply drafts", "description": "List owner-reviewed agent reply drafts. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "description": "interaction id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List owner-reviewed agent reply drafts response", "content": { "application/json": { "schema": { "type": "object", "description": "Compatibility response for owner-scoped reply drafts. Returns an empty collection until the reviewed-draft workflow is enabled.", "additionalProperties": true, "required": [ "schema_version", "interaction_id", "drafts" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/messages/{interaction_id}/reply": { "post": { "tags": [ "Business Owner" ], "summary": "Reply to customer message", "description": "Reply to customer message. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "interaction_id", "in": "path", "required": true, "description": "interaction id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "body", "client_message_id" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "client_message_id": { "type": "string", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$" } } } } } }, "responses": { "200": { "description": "Reply to customer message response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner reply result.", "additionalProperties": true, "required": [ "status", "reply" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agents": { "get": { "tags": [ "Customer Account" ], "summary": "List my personal agents", "description": "List my personal agents. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "responses": { "200": { "description": "List my personal agents response", "content": { "application/json": { "schema": { "type": "object", "description": "Customer-owned personal agents; secrets are never returned.", "additionalProperties": true, "required": [ "account_id", "allowed_actions", "mcp_endpoint", "agents" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Customer Account" ], "summary": "Connect personal agent", "description": "Connect personal agent. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Connect personal agent response", "content": { "application/json": { "schema": { "type": "object", "description": "Connected personal agent; raw key is returned once.", "additionalProperties": true, "required": [ "status", "agent", "raw_key", "one_time_display", "mcp_endpoint" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/conversations": { "get": { "tags": [ "Customer Account" ], "summary": "List my conversations", "description": "List my conversations. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List my conversations response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "generated_at", "count", "conversations" ], "properties": { "schema_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "count": { "type": "integer", "minimum": 0 }, "conversations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "conversation_id", "business_id", "business_name", "subject", "message", "status", "workflow_status", "created_at", "last_activity_at", "counterparty_read_at", "unread", "replies" ], "properties": { "conversation_id": { "type": "string" }, "business_id": { "type": "string" }, "business_name": { "type": "string" }, "subject": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "workflow_status": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "last_activity_at": { "type": [ "string", "null" ] }, "counterparty_read_at": { "type": [ "string", "null" ] }, "unread": { "type": "boolean" }, "replies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "body", "author_type", "author_label", "created_at", "ai_assisted", "attachment_id", "attachment_file_name", "attachment_media_type", "attachment_byte_size", "client_message_id" ], "properties": { "body": { "type": "string" }, "author_type": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "ai_assisted": { "type": "boolean" }, "attachment_id": { "type": [ "string", "null" ] }, "attachment_file_name": { "type": [ "string", "null" ] }, "attachment_media_type": { "type": [ "string", "null" ] }, "attachment_byte_size": { "type": [ "integer", "null" ], "minimum": 1 }, "client_message_id": { "type": [ "string", "null" ] } } } } } } } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agents/{agent_id}/rotate-key": { "post": { "tags": [ "Customer Account" ], "summary": "Rotate personal-agent key", "description": "Rotate personal-agent key. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate personal-agent key response", "content": { "application/json": { "schema": { "type": "object", "description": "Rotated personal-agent key; raw key is returned once.", "additionalProperties": true, "required": [ "status", "agent", "raw_key", "one_time_display", "mcp_endpoint" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agents/{agent_id}/disconnect": { "post": { "tags": [ "Customer Account" ], "summary": "Disconnect personal agent", "description": "Disconnect personal agent. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disconnect personal agent response", "content": { "application/json": { "schema": { "type": "object", "description": "Personal-agent disconnection result.", "additionalProperties": true, "required": [ "status", "key_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agents/{agent_id}/webhook": { "get": { "tags": [ "Customer Account" ], "summary": "Get personal-agent webhook", "description": "Returns the signed HTTPS wake-up endpoint bound to the signed-in customer's one active external-agent key. The response never reveals the one-time signing secret or the agent API key.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get personal-agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Customer Account" ], "summary": "Register personal-agent webhook", "description": "Human-customer registration of a provider-neutral HTTPS wake-up receiver for the one active personal-agent credential. Loppee sends reference-only business.message.replied events; the receiver verifies the HMAC and uses its separately scoped Loppee API/MCP key to fetch the conversation. Re-registering replaces the endpoint and rotates the signing secret, which is returned once.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048, "description": "Public HTTPS receiver operated by the connecting principal or its agent runtime. Credentials in the URL and private-network destinations are rejected." } } } } } }, "responses": { "200": { "description": "Register personal-agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint", "signing_secret", "one_time_display", "delivery_contract" ], "properties": { "status": { "type": "string", "enum": [ "registered", "rotated" ] }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "signing_secret": { "type": "string", "pattern": "^loppee_whsec_", "minLength": 32 }, "one_time_display": { "const": true }, "delivery_contract": { "type": "object", "additionalProperties": false, "required": [ "version", "authentication", "payload_mode" ], "properties": { "version": { "const": "loppee.webhook.v1" }, "authentication": { "const": "hmac_sha256" }, "payload_mode": { "const": "reference_only" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agents/{agent_id}/webhook/disable": { "post": { "tags": [ "Customer Account" ], "summary": "Disable personal-agent webhook", "description": "Human-customer disablement of wake-up deliveries for this personal agent. The webhook carries no message body, customer data, or authority.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disable personal-agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint" ], "properties": { "status": { "const": "disabled" }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/agents/{agent_id}/webhook/test": { "post": { "tags": [ "Customer Account" ], "summary": "Test personal-agent webhook", "description": "Human-customer enqueue of a signed agent.webhook.test wake-up event through the live signing and delivery path. It is receipt-only: the receiver validates the signature/timestamp and returns 2xx without fetching a resource.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test personal-agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "event_id", "endpoint_id" ], "properties": { "status": { "const": "queued" }, "event_id": { "type": "string" }, "endpoint_id": { "type": "string" } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/conversations/{conversation_id}/reply": { "post": { "tags": [ "Customer Account" ], "summary": "Reply to a business conversation", "description": "Reply to a business conversation. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "body", "client_message_id" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "client_message_id": { "type": "string", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$" } } } } } }, "responses": { "200": { "description": "Reply to a business conversation response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "reply" ], "properties": { "status": { "type": "string", "enum": [ "replied" ] }, "reply": { "type": "object", "additionalProperties": false, "required": [ "id", "body", "author_type", "author_label", "created_at", "client_message_id", "idempotent_replay" ], "properties": { "id": { "type": "string" }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "author_type": { "type": "string", "enum": [ "customer" ] }, "author_label": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "client_message_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,80}$" }, "idempotent_replay": { "type": "boolean" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/conversations/{conversation_id}/read": { "post": { "tags": [ "Customer Account" ], "summary": "Mark customer conversation read", "description": "Mark customer conversation read. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mark customer conversation read response", "content": { "application/json": { "schema": { "type": "object", "description": "Durable customer read acknowledgement.", "additionalProperties": true, "required": [ "status", "conversation_id", "read_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/support": { "get": { "tags": [ "Business Owner" ], "summary": "Get owner support thread", "description": "Get owner support thread. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "responses": { "200": { "description": "Get owner support thread response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner-scoped Loppee support thread.", "additionalProperties": true, "required": [ "schema_version", "generated_at", "owner", "conversations" ], "properties": { "schema_version": { "type": "string" }, "generated_at": { "type": "string" }, "owner": { "type": "object", "description": "Signed-in owner's own support identity.", "additionalProperties": true }, "conversations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "ownerUserId", "ownerEmail", "ownerName", "businessId", "businessName", "subject", "status", "assigneeType", "assigneeId", "assigneeLabel", "ownerLastReadAt", "supportLastReadAt", "lastMessageAt", "lastMessagePreview", "lastMessageAuthorType", "createdAt", "updatedAt", "messagesTruncated", "messages" ], "properties": { "id": { "type": "string" }, "ticketNumber": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerEmail": { "type": "string" }, "ownerName": { "type": "string" }, "businessId": { "type": "string" }, "businessName": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assigneeType": { "type": "string", "enum": [ "human", "agent" ] }, "assigneeId": { "type": "string" }, "assigneeLabel": { "type": "string" }, "ownerLastReadAt": { "type": [ "string", "null" ] }, "supportLastReadAt": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ] }, "lastMessagePreview": { "type": "string" }, "lastMessageAuthorType": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "messagesTruncated": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } } } } } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/support/messages": { "post": { "tags": [ "Business Owner" ], "summary": "Send owner support message", "description": "Send owner support message. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "body" ], "properties": { "business_id": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" } } } } } }, "responses": { "200": { "description": "Send owner support message response", "content": { "application/json": { "schema": { "type": "object", "description": "Support message result.", "additionalProperties": true, "required": [ "status", "outbound_delivery", "conversation" ], "properties": { "conversation": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "ownerUserId", "ownerEmail", "ownerName", "businessId", "businessName", "subject", "status", "assigneeType", "assigneeId", "assigneeLabel", "ownerLastReadAt", "supportLastReadAt", "lastMessageAt", "lastMessagePreview", "lastMessageAuthorType", "createdAt", "updatedAt", "messagesTruncated", "messages" ], "properties": { "id": { "type": "string" }, "ticketNumber": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerEmail": { "type": "string" }, "ownerName": { "type": "string" }, "businessId": { "type": "string" }, "businessName": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assigneeType": { "type": "string", "enum": [ "human", "agent" ] }, "assigneeId": { "type": "string" }, "assigneeLabel": { "type": "string" }, "ownerLastReadAt": { "type": [ "string", "null" ] }, "supportLastReadAt": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ] }, "lastMessagePreview": { "type": "string" }, "lastMessageAuthorType": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "messagesTruncated": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/support/{conversation_id}/messages": { "get": { "tags": [ "Business Owner" ], "summary": "Page owner support messages", "description": "Page owner support messages. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "before query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Page owner support messages response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "conversation_id", "messages", "has_more" ], "properties": { "conversation_id": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } }, "has_more": { "type": "boolean" } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/support/{conversation_id}/typing": { "post": { "tags": [ "Business Owner" ], "summary": "Set owner support typing state", "description": "Set owner support typing state. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "typing": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Set owner support typing state response", "content": { "application/json": { "schema": { "type": "object", "description": "Ephemeral support typing state.", "additionalProperties": true, "required": [ "status", "conversation_id", "counterpart_typing", "counterpart_label" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/support/{conversation_id}/read": { "post": { "tags": [ "Business Owner" ], "summary": "Mark owner support conversation read", "description": "Mark owner support conversation read. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mark owner support conversation read response", "content": { "application/json": { "schema": { "type": "object", "description": "Durable support read acknowledgement.", "additionalProperties": true, "required": [ "status", "conversation_id", "read_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/contact-attempt": { "post": { "tags": [ "Moderated Actions" ], "summary": "Record Loppee contact attempt", "description": "Record Loppee contact attempt. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "target_business_id" ], "properties": { "target_business_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "quote_request", "call_request", "booking_request" ] }, "client_request_id": { "type": "string", "maxLength": 160 }, "subject": { "type": "string" }, "message": { "type": "string" }, "human_confirmation": { "type": "boolean" }, "searcher_latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "searcher_longitude": { "type": "number", "minimum": -180, "maximum": 180 } }, "dependentRequired": { "searcher_latitude": [ "searcher_longitude" ], "searcher_longitude": [ "searcher_latitude" ] } } } } }, "responses": { "200": { "description": "Record Loppee contact attempt response", "content": { "application/json": { "schema": { "type": "object", "description": "Versioned contact result. Under v3 this is a plan-neutral request delivery; it never claims a call connected or a booking completed.", "additionalProperties": true, "required": [ "status", "target_business_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/businesses/{business_id}/my-review": { "get": { "tags": [ "Trust Cards" ], "summary": "Get my review for a business", "description": "Get my review for a business. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get my review for a business response", "content": { "application/json": { "schema": { "type": "object", "description": "The signed-in customer's own review, or an explicit absent result.", "additionalProperties": true, "required": [ "review" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/reviews/{review_id}/respond": { "post": { "tags": [ "Business Owner" ], "summary": "Respond to business review", "description": "Respond to business review. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "review_id", "in": "path", "required": true, "description": "review id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "body" ], "properties": { "body": { "type": "string" } } } } } }, "responses": { "200": { "description": "Respond to business review response", "content": { "application/json": { "schema": { "type": "object", "description": "Owner review response.", "additionalProperties": true, "required": [ "responseId", "publishedAt", "edited" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/reviews/{review_id}/report": { "post": { "tags": [ "Business Owner" ], "summary": "Report business review", "description": "Report business review. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "parameters": [ { "name": "review_id", "in": "path", "required": true, "description": "review id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "reason_category": { "type": "string" }, "reason_detail": { "type": "string" } } } } } }, "responses": { "200": { "description": "Report business review response", "content": { "application/json": { "schema": { "type": "object", "description": "Review-report result.", "additionalProperties": true, "required": [ "status", "report_id", "review_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/stripe/webhook": { "post": { "tags": [ "Moderated Actions" ], "summary": "Receive Stripe webhook", "description": "Receive Stripe webhook. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "StripeSignature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Raw Stripe event JSON. The Stripe-Signature header is required and verified before processing.", "additionalProperties": true } } } }, "responses": { "200": { "description": "Receive Stripe webhook response", "content": { "application/json": { "schema": { "type": "object", "description": "Verified Stripe event handling result.", "additionalProperties": true, "required": [ "received", "handled", "type" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support": { "get": { "tags": [ "Operations" ], "summary": "List support inbox", "description": "List support inbox. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "q query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List support inbox response", "content": { "application/json": { "schema": { "type": "object", "description": "Permission-scoped support inbox.", "additionalProperties": true, "required": [ "schema_version", "generated_at", "staff", "conversations", "total", "limit", "offset" ], "properties": { "schema_version": { "type": "string" }, "generated_at": { "type": "string" }, "staff": { "type": "object", "description": "Authenticated support staff identity.", "additionalProperties": true }, "conversations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "ownerUserId", "ownerEmail", "ownerName", "businessId", "businessName", "subject", "status", "assigneeType", "assigneeId", "assigneeLabel", "ownerLastReadAt", "supportLastReadAt", "lastMessageAt", "lastMessagePreview", "lastMessageAuthorType", "createdAt", "updatedAt", "messagesTruncated", "messages" ], "properties": { "id": { "type": "string" }, "ticketNumber": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerEmail": { "type": "string" }, "ownerName": { "type": "string" }, "businessId": { "type": "string" }, "businessName": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assigneeType": { "type": "string", "enum": [ "human", "agent" ] }, "assigneeId": { "type": "string" }, "assigneeLabel": { "type": "string" }, "ownerLastReadAt": { "type": [ "string", "null" ] }, "supportLastReadAt": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ] }, "lastMessagePreview": { "type": "string" }, "lastMessageAuthorType": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "messagesTruncated": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } } } } }, "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/indicator": { "get": { "tags": [ "Operations" ], "summary": "Get support inbox indicator", "description": "Get support inbox indicator. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "responses": { "200": { "description": "Get support inbox indicator response", "content": { "application/json": { "schema": { "type": "object", "description": "Open and pending support counts.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/messages": { "get": { "tags": [ "Operations" ], "summary": "Page support messages", "description": "Page support messages. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "before query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Page support messages response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "conversation_id", "messages", "has_more" ], "properties": { "conversation_id": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } }, "has_more": { "type": "boolean" } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/typing": { "post": { "tags": [ "Operations" ], "summary": "Set staff support typing state", "description": "Set staff support typing state. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "typing": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Set staff support typing state response", "content": { "application/json": { "schema": { "type": "object", "description": "Ephemeral staff typing state.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/reply": { "post": { "tags": [ "Operations" ], "summary": "Reply to support conversation", "description": "Human respond_messages + AAL2 only. ai_draft_id is optional only when the conversation has no pending AI draft. A pending draft must be sent with its id or explicitly discarded; linked human-reviewed messages remain visibly labeled AI-assisted.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "body" ], "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "ai_draft_id": { "type": "string", "minLength": 1, "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Reply to support conversation response", "content": { "application/json": { "schema": { "type": "object", "description": "Human support reply result.", "additionalProperties": true, "required": [ "conversation" ], "properties": { "conversation": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "ownerUserId", "ownerEmail", "ownerName", "businessId", "businessName", "subject", "status", "assigneeType", "assigneeId", "assigneeLabel", "ownerLastReadAt", "supportLastReadAt", "lastMessageAt", "lastMessagePreview", "lastMessageAuthorType", "createdAt", "updatedAt", "messagesTruncated", "messages" ], "properties": { "id": { "type": "string" }, "ticketNumber": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerEmail": { "type": "string" }, "ownerName": { "type": "string" }, "businessId": { "type": "string" }, "businessName": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assigneeType": { "type": "string", "enum": [ "human", "agent" ] }, "assigneeId": { "type": "string" }, "assigneeLabel": { "type": "string" }, "ownerLastReadAt": { "type": [ "string", "null" ] }, "supportLastReadAt": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ] }, "lastMessagePreview": { "type": "string" }, "lastMessageAuthorType": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "messagesTruncated": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/assign": { "post": { "tags": [ "Operations" ], "summary": "Assign support conversation", "description": "Assign support conversation. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "action": { "type": "string" }, "assignee_id": { "type": "string" }, "assignee_label": { "type": "string" }, "assignee_type": { "type": "string", "enum": [ "human" ], "description": "AI assignment is unavailable while the customer-support workload is disconnected." } } } } } }, "responses": { "200": { "description": "Assign support conversation response", "content": { "application/json": { "schema": { "type": "object", "description": "Support assignment result.", "additionalProperties": true, "required": [ "conversation" ], "properties": { "conversation": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "ownerUserId", "ownerEmail", "ownerName", "businessId", "businessName", "subject", "status", "assigneeType", "assigneeId", "assigneeLabel", "ownerLastReadAt", "supportLastReadAt", "lastMessageAt", "lastMessagePreview", "lastMessageAuthorType", "createdAt", "updatedAt", "messagesTruncated", "messages" ], "properties": { "id": { "type": "string" }, "ticketNumber": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerEmail": { "type": "string" }, "ownerName": { "type": "string" }, "businessId": { "type": "string" }, "businessName": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assigneeType": { "type": "string", "enum": [ "human", "agent" ] }, "assigneeId": { "type": "string" }, "assigneeLabel": { "type": "string" }, "ownerLastReadAt": { "type": [ "string", "null" ] }, "supportLastReadAt": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ] }, "lastMessagePreview": { "type": "string" }, "lastMessageAuthorType": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "messagesTruncated": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/status": { "post": { "tags": [ "Operations" ], "summary": "Set support conversation status", "description": "Set support conversation status. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "status" ], "properties": { "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Set support conversation status response", "content": { "application/json": { "schema": { "type": "object", "description": "Support status update result.", "additionalProperties": true, "required": [ "conversation" ], "properties": { "conversation": { "type": "object", "additionalProperties": false, "required": [ "id", "ticketNumber", "ownerUserId", "ownerEmail", "ownerName", "businessId", "businessName", "subject", "status", "assigneeType", "assigneeId", "assigneeLabel", "ownerLastReadAt", "supportLastReadAt", "lastMessageAt", "lastMessagePreview", "lastMessageAuthorType", "createdAt", "updatedAt", "messagesTruncated", "messages" ], "properties": { "id": { "type": "string" }, "ticketNumber": { "type": "string" }, "ownerUserId": { "type": "string" }, "ownerEmail": { "type": "string" }, "ownerName": { "type": "string" }, "businessId": { "type": "string" }, "businessName": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "closed" ] }, "assigneeType": { "type": "string", "enum": [ "human", "agent" ] }, "assigneeId": { "type": "string" }, "assigneeLabel": { "type": "string" }, "ownerLastReadAt": { "type": [ "string", "null" ] }, "supportLastReadAt": { "type": [ "string", "null" ] }, "lastMessageAt": { "type": [ "string", "null" ] }, "lastMessagePreview": { "type": "string" }, "lastMessageAuthorType": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "messagesTruncated": { "type": "boolean" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "conversationId", "authorType", "authorLabel", "body", "aiAssisted", "createdAt" ], "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "authorType": { "type": "string", "enum": [ "owner", "support", "agent" ] }, "authorLabel": { "type": "string" }, "body": { "type": "string", "maxLength": 4000 }, "aiAssisted": { "type": "boolean", "description": "True only when the reply is linked to a human-reviewed AI draft. Customer-facing clients must render a visible AI-assisted label when true." }, "createdAt": { "type": [ "string", "null" ] } } } } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/read": { "post": { "tags": [ "Operations" ], "summary": "Mark support conversation read", "description": "Mark support conversation read. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mark support conversation read response", "content": { "application/json": { "schema": { "type": "object", "description": "Durable staff read acknowledgement.", "additionalProperties": true, "required": [ "status" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ai-connections": { "get": { "tags": [ "Operations" ], "summary": "Get safe AI provider control-plane state", "description": "Requires a human administrator with manage_team permission and AAL2. Returns provider metadata, server-approved models, and workload bindings, but never a credential, Vault reference, key fragment, or fingerprint.", "security": [ { "SupabaseAdminBearer": [] } ], "responses": { "200": { "description": "Get safe AI provider control-plane state response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "mode", "provider_egress_enabled", "customer_data_egress_enabled", "live_calls_enabled", "providers", "workloads", "policies" ], "properties": { "schema_version": { "type": "string", "const": "1.0" }, "mode": { "type": "string", "const": "setup_ready" }, "provider_egress_enabled": { "type": "boolean" }, "customer_data_egress_enabled": { "type": "boolean" }, "live_calls_enabled": { "type": "boolean" }, "providers": { "type": "array", "minItems": 3, "maxItems": 3, "prefixItems": [ { "type": "object", "additionalProperties": false, "required": [ "id", "label", "availability", "model_options", "connection" ], "properties": { "id": { "type": "string", "const": "openai" }, "label": { "type": "string", "const": "OpenAI" }, "availability": { "type": "string", "const": "planned" }, "model_options": { "type": "array", "minItems": 0, "maxItems": 0, "items": false }, "connection": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "label", "status", "verified_at", "last_probe_at", "last_error_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "disconnected" ] }, "verified_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_probe_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_error_code": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]{0,79}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "label", "availability", "model_options", "connection" ], "properties": { "id": { "type": "string", "const": "anthropic" }, "label": { "type": "string", "const": "Anthropic (Claude)" }, "availability": { "type": "string", "const": "planned" }, "model_options": { "type": "array", "minItems": 0, "maxItems": 0, "items": false }, "connection": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "label", "status", "verified_at", "last_probe_at", "last_error_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "disconnected" ] }, "verified_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_probe_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_error_code": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]{0,79}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "label", "availability", "model_options", "connection" ], "properties": { "id": { "type": "string", "const": "google_gemini" }, "label": { "type": "string", "const": "Google Gemini" }, "availability": { "type": "string", "const": "setup_ready" }, "model_options": { "type": "array", "minItems": 2, "maxItems": 2, "prefixItems": [ { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "const": "gemini-3.5-flash" }, "label": { "type": "string", "const": "Gemini 3.5 Flash — higher quality" } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "label" ], "properties": { "id": { "type": "string", "const": "gemini-3.1-flash-lite" }, "label": { "type": "string", "const": "Gemini 3.1 Flash-Lite — lower cost" } } } ], "items": false }, "connection": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "label", "status", "verified_at", "last_probe_at", "last_error_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "disconnected" ] }, "verified_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_probe_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_error_code": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]{0,79}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] } } } ], "items": false }, "workloads": { "type": "array", "minItems": 3, "maxItems": 3, "prefixItems": [ { "type": "object", "additionalProperties": false, "required": [ "id", "label", "binding" ], "properties": { "id": { "type": "string", "const": "backoffice" }, "label": { "type": "string", "const": "Back-office assistant" }, "binding": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "workload", "connection_id", "provider", "model_id", "enabled", "updated_at" ], "properties": { "workload": { "type": "string", "const": "backoffice" }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "model_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean", "const": false }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "label", "binding" ], "properties": { "id": { "type": "string", "const": "customer_support" }, "label": { "type": "string", "const": "Loppee Support copilot" }, "binding": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "workload", "connection_id", "provider", "model_id", "enabled", "updated_at" ], "properties": { "workload": { "type": "string", "const": "customer_support" }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "model_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "id", "label", "binding" ], "properties": { "id": { "type": "string", "const": "evidence_research" }, "label": { "type": "string", "const": "Evidence research & source checks" }, "binding": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "workload", "connection_id", "provider", "model_id", "enabled", "updated_at" ], "properties": { "workload": { "type": "string", "const": "evidence_research" }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "model_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean", "const": false }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, { "type": "null" } ] } } } ], "items": false }, "policies": { "type": "object", "additionalProperties": false, "required": [ "evidence_authority", "customer_support", "backoffice" ], "properties": { "evidence_authority": { "type": "string", "const": "LLM output alone has zero verification authority. Only a qualifying immutable receipt recorded by Loppee's controlled automatic or audited-manual authority can satisfy a factor; the caller cannot set the class." }, "customer_support": { "type": "string", "const": "Customer-support AI is draft-only and must be clearly labeled as AI. A human sends every customer-facing reply and human handoff is always available. AI cannot change a business's Verified/Listed class, publication, eligibility, reviews, or ranking." }, "backoffice": { "type": "string", "const": "Back-office AI is read-only. It may search and draft, but cannot mutate records or receive a service-role credential. Connection, rotation, disconnection, and workload changes require a human administrator with recent AAL2 authentication." } } } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Operations" ], "summary": "Connect and verify an AI provider", "description": "Human manage_team + AAL2 only. The write-only credential is probed server-side and stored through the Vault boundary; it is never returned. Connecting a provider does not enable any workload.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "provider", "api_key" ], "properties": { "provider": { "type": "string", "const": "google_gemini" }, "api_key": { "type": "string", "minLength": 8, "maxLength": 4096, "writeOnly": true } } } } } }, "responses": { "200": { "description": "Connect and verify an AI provider response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "connection" ], "properties": { "status": { "type": "string", "const": "verified" }, "connection": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "label", "status", "verified_at", "last_probe_at", "last_error_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "disconnected" ] }, "verified_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_probe_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_error_code": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]{0,79}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ai-connections/{connection_id}/test": { "post": { "tags": [ "Operations" ], "summary": "Test an AI provider connection", "description": "Human manage_team + AAL2 only. Performs a bounded authenticated provider probe. A failed candidate probe cannot replace a previously verified active credential.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "description": "connection id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test an AI provider connection response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "connection", "probe" ], "properties": { "status": { "type": "string", "enum": [ "verified", "failed" ] }, "connection": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "label", "status", "verified_at", "last_probe_at", "last_error_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "disconnected" ] }, "verified_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_probe_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_error_code": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]{0,79}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "probe": { "type": "object", "additionalProperties": false, "required": [ "checked_at", "latency_ms" ], "properties": { "checked_at": { "type": "string", "minLength": 1, "maxLength": 64 }, "latency_ms": { "type": "number", "minimum": 0 } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ai-connections/{connection_id}/rotate": { "post": { "tags": [ "Operations" ], "summary": "Rotate and verify an AI provider credential", "description": "Human manage_team + AAL2 only. Stores the write-only key as a candidate, verifies it, and promotes it atomically; a failed probe preserves the active credential and enabled workloads.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "description": "connection id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "minLength": 8, "maxLength": 4096, "writeOnly": true } } } } } }, "responses": { "200": { "description": "Rotate and verify an AI provider credential response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "connection" ], "properties": { "status": { "type": "string", "const": "verified" }, "connection": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "label", "status", "verified_at", "last_probe_at", "last_error_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "disconnected" ] }, "verified_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_probe_at": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "last_error_code": { "anyOf": [ { "type": "string", "pattern": "^[a-z0-9][a-z0-9_.-]{0,79}$" }, { "type": "null" } ] }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ai-connections/{connection_id}": { "delete": { "tags": [ "Operations" ], "summary": "Disconnect an AI provider", "description": "Human manage_team + AAL2 only. Disables dependent workloads before deleting active and candidate Vault credentials.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "connection_id", "in": "path", "required": true, "description": "connection id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disconnect an AI provider response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "connection_id" ], "properties": { "status": { "type": "string", "const": "disconnected" }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 128 } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ai-workload-bindings/{workload}": { "put": { "tags": [ "Operations" ], "summary": "Configure an AI workload binding", "description": "Human manage_team + AAL2 only. Binds exactly one workload to a verified provider and server-approved model. Workloads remain isolated and cannot grant verification authority.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "workload", "in": "path", "required": true, "description": "workload path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "connection_id", "model_id", "enabled" ], "properties": { "connection_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "model_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Configure an AI workload binding response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "binding" ], "properties": { "status": { "type": "string", "const": "updated" }, "binding": { "type": "object", "additionalProperties": false, "required": [ "workload", "connection_id", "provider", "model_id", "enabled", "updated_at" ], "properties": { "workload": { "type": "string", "enum": [ "backoffice", "customer_support", "evidence_research" ] }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "model_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "enabled": { "type": "boolean" }, "updated_at": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Operations" ], "summary": "Disable and remove an AI workload binding", "description": "Disable and remove an AI workload binding. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "workload", "in": "path", "required": true, "description": "workload path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disable and remove an AI workload binding response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "workload" ], "properties": { "status": { "type": "string", "const": "disabled" }, "workload": { "type": "string", "enum": [ "backoffice", "customer_support", "evidence_research" ] } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/ai-status": { "get": { "tags": [ "Operations" ], "summary": "Get support-copilot availability", "description": "Human respond_messages + AAL2 only. Returns a minimal capability status without exposing provider metadata or credentials.", "security": [ { "SupabaseAdminBearer": [] } ], "responses": { "200": { "description": "Get support-copilot availability response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "available", "reason" ], "oneOf": [ { "properties": { "available": { "type": "boolean", "const": true }, "reason": { "type": "string", "const": "ready" } } }, { "properties": { "available": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "runtime_off", "not_configured" ] } } } ], "properties": { "available": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "ready", "runtime_off", "not_configured" ] } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/ai-draft": { "post": { "tags": [ "Operations" ], "summary": "Create a support-copilot draft", "description": "Human respond_messages + AAL2 only. Creates a separate AI-labeled draft for review. It never inserts a support message, sends a reply, or performs an account action.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "instruction": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "Create a support-copilot draft response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "draft", "run" ], "properties": { "status": { "type": "string", "const": "draft" }, "draft": { "type": "object", "additionalProperties": false, "required": [ "id", "conversation_id", "body", "created_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "run": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "model_id", "provider_request_id", "finish_reason", "input_tokens", "output_tokens", "thinking_tokens", "total_tokens", "cost_micros", "currency" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider": { "type": "string", "enum": [ "openai", "anthropic", "google_gemini" ] }, "model_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "provider_request_id": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] }, "finish_reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "input_tokens": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "output_tokens": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "thinking_tokens": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "total_tokens": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "cost_micros": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "USD" }, { "type": "null" } ] } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/ai-drafts/{draft_id}": { "delete": { "tags": [ "Operations" ], "summary": "Discard a pending support-copilot draft", "description": "Human respond_messages + AAL2 only. Records an immutable discard receipt for an unsent draft. Until a pending draft is sent with its id or explicitly discarded, ordinary staff replies fail closed so AI-assisted text cannot be sent without its visible label.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } }, { "name": "draft_id", "in": "path", "required": true, "description": "draft id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Discard a pending support-copilot draft response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "draft_id", "conversation_id", "discarded_text_will_not_be_used" ], "properties": { "status": { "type": "string", "const": "discarded" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "discarded_text_will_not_be_used": { "type": "boolean", "const": true } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/support/{conversation_id}/ai-drafts/pending": { "get": { "tags": [ "Operations" ], "summary": "List unresolved support-copilot draft receipts", "description": "Human respond_messages + AAL2 only. Returns unresolved draft ids and creation timestamps for crash/refresh recovery. It never returns draft text, hashes, provider metadata, or run metadata.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "description": "conversation id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List unresolved support-copilot draft receipts response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "conversation_id", "pending_drafts" ], "properties": { "conversation_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "pending_drafts": { "type": "array", "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "created_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "created_at": { "type": "string", "minLength": 1, "maxLength": 64 } } } } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/agent-keys/principals/{principal_id}": { "get": { "tags": [ "Operations" ], "summary": "Get agent-key principal", "description": "Get agent-key principal. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "principal_id", "in": "path", "required": true, "description": "principal id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get agent-key principal response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited masked key inventory for one principal.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/business-claims": { "get": { "tags": [ "Operations" ], "summary": "List business claims (server-paginated)", "description": "review_intake. Pages the FULL claims table with an exact server count — the claims workspace never depends on the browser's bounded bootstrap window. filter=open (default, oldest first) or all (newest first); limit/offset.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "responses": { "200": { "description": "List business claims (server-paginated) response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated claim rows with resolved business display context.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/business-claims/{claim_id}/review": { "post": { "tags": [ "Operations" ], "summary": "Review business claim", "description": "Reject and evidence_needed require review_intake. Approve grants ownership and requires a signed human admin with verify_evidence plus a fresh strong-factor step-up; admin-agent keys cannot approve.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "claim_id", "in": "path", "required": true, "description": "claim id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject", "evidence_needed" ] }, "review_notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Review business claim response", "content": { "application/json": { "schema": { "type": "object", "description": "Claim review result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/overview": { "get": { "tags": [ "Operations" ], "summary": "Get admin overview", "description": "Get admin overview. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "responses": { "200": { "description": "Get admin overview response", "content": { "application/json": { "schema": { "type": "object", "description": "Back-office overview aggregate.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses": { "post": { "tags": [ "Operations" ], "summary": "Create intake business", "description": "Create intake business. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "display_name", "taxonomy_category_aliases" ], "properties": { "display_name": { "type": "string" }, "legal_name": { "type": "string" }, "category": { "type": "string" }, "taxonomy_category_aliases": { "type": "array", "items": { "type": "string" } }, "phone": { "type": "string" }, "website": { "type": "string" }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "dedupe_ack": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Create intake business response", "content": { "application/json": { "schema": { "type": "object", "description": "Created intake record; creation never implies publication or verification.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/exposure-tier": { "post": { "tags": [ "Operations" ], "summary": "Set business exposure tier", "description": "Set business exposure tier. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "tier" ], "properties": { "tier": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Set business exposure tier response", "content": { "application/json": { "schema": { "type": "object", "description": "Admin exposure-tier update. Payment never changes trust or eligibility.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/category": { "post": { "tags": [ "Operations" ], "summary": "Set exact business category", "description": "Set exact business category. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "taxonomy_category_aliases" ], "properties": { "category": { "type": "string" }, "taxonomy_category_aliases": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Set exact business category response", "content": { "application/json": { "schema": { "type": "object", "description": "Taxonomy category update and applicability recomputation.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/category-requests": { "get": { "tags": [ "Operations" ], "summary": "List category requests", "description": "List category requests. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List category requests response", "content": { "application/json": { "schema": { "type": "object", "description": "Admin category-request queue.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/category-requests/{request_id}/review": { "post": { "tags": [ "Operations" ], "summary": "Review category request", "description": "Review category request. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "request_id", "in": "path", "required": true, "description": "request id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "approve", "reject" ] }, "reject_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Review category request response", "content": { "application/json": { "schema": { "type": "object", "description": "Category-request review result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/lifecycle": { "post": { "tags": [ "Operations" ], "summary": "Set business lifecycle state", "description": "Set business lifecycle state. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "action" ], "properties": { "action": { "type": "string" }, "reason_code": { "type": "string" }, "reason_detail": { "type": "string" }, "confirm": { "type": "string" } } } } } }, "responses": { "200": { "description": "Set business lifecycle state response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited business lifecycle transition.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/dashboard": { "get": { "tags": [ "Operations" ], "summary": "Get business-ops dashboard", "description": "Get business-ops dashboard. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "responses": { "200": { "description": "Get business-ops dashboard response", "content": { "application/json": { "schema": { "type": "object", "description": "Business-operations aggregate.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/businesses": { "get": { "tags": [ "Operations" ], "summary": "List business-ops pipeline", "description": "List business-ops pipeline. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "claim_status", "in": "query", "required": false, "description": "claim status query filter.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "source query filter.", "schema": { "type": "string" } }, { "name": "verification_state", "in": "query", "required": false, "description": "verification state query filter.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "category query filter.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "state query filter.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "sort query filter.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "cursor query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List business-ops pipeline response", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor-paginated business-ops pipeline.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/verification-cases": { "get": { "tags": [ "Operations" ], "summary": "List verification cases", "description": "List verification cases. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "required": false, "description": "filter query filter.", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "description": "cursor query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List verification cases response", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor-paginated verification work queue.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/verification-cases/{business_id}": { "get": { "tags": [ "Operations" ], "summary": "Get verification case file", "description": "Get verification case file. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get verification case file response", "content": { "application/json": { "schema": { "type": "object", "description": "Complete audited verification case file.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/verification-cases/{business_id}/management": { "patch": { "tags": [ "Operations" ], "summary": "Update verification case management", "description": "Update verification case management. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "reason_code", "expected_version" ], "properties": { "case_status": { "type": "string" }, "priority": { "type": "string" }, "assigned_admin_user_id": { "type": [ "string", "null" ] }, "sla_due_at": { "type": [ "string", "null" ] }, "reason_code": { "type": "string" }, "expected_version": { "type": "number" } } } } } }, "responses": { "200": { "description": "Update verification case management response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited verification case coordination update.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/v3/verification-exceptions": { "get": { "tags": [ "Operations" ], "summary": "List Trust Model v3 verification exceptions", "description": "List Trust Model v3 verification exceptions. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } }, { "name": "warning_days", "in": "query", "required": false, "description": "warning days query filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List Trust Model v3 verification exceptions response", "content": { "application/json": { "schema": { "type": "object", "description": "Private v3 automatic-check exception and expiry queue.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/v3/manual-verification-submissions/count": { "get": { "tags": [ "Operations" ], "summary": "Count Trust Model v3 manual-verification submissions", "description": "Queue depth only — a number, no rows, identifiers, or documents. Gated on the same durable complete_manual_verification permission as the queue but WITHOUT the fresh step-up requirement: a routine dashboard load may show how many submissions wait, while the queue contents and every decision stay behind the step-up-gated endpoints.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Count Trust Model v3 manual-verification submissions response", "content": { "application/json": { "schema": { "type": "object", "description": "Manual-verification queue depth.", "additionalProperties": true, "required": [ "schema_version", "trust_model_version", "status", "total" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/v3/manual-verification-submissions": { "get": { "tags": [ "Operations" ], "summary": "List Trust Model v3 manual-verification submissions", "description": "Returns private pending or historical entity/license submissions only to a human with fresh AAL2 or a back-office agent whose exact active key carries complete_manual_verification. Raw storage references are never returned; any document URL is short lived. Licence rows include the business taxonomy aliases required for exact, non-wildcard scope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List Trust Model v3 manual-verification submissions response", "content": { "application/json": { "schema": { "type": "object", "description": "Private audited-manual entity/license queue.", "additionalProperties": true, "required": [ "schema_version", "trust_model_version", "status", "total", "rows" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/v3/manual-verification-submissions/{submission_id}/decision": { "post": { "tags": [ "Operations" ], "summary": "Decide a Trust Model v3 manual-verification submission", "description": "Approves or rejects one current private entity/license submission. A human needs fresh AAL2 and complete_manual_verification; an external back-office agent needs that exact action on its active key. The submitter and current business owners cannot approve. Rejection should include a controlled owner_reason_code and always carries a separate private audited reason; for backward compatibility only, an omitted rejection code maps to the controlled generic other copy. Approval forbids owner_reason_code. Every official_source_manual decision requires the exact nonempty authority name and valid HTTPS source URL; document_review cannot carry an external source. official_record_not_found is additionally limited to a rejected official_source_manual review. Approval requires method-specific checks, reviewer-supplied validity within the factor/method ceiling, exact non-wildcard taxonomy scope for a licence, and exact type-to-confirm. The Loppee service writes the receipt and derives class; the caller cannot set either.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "submission_id", "in": "path", "required": true, "description": "submission id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "outcome", "verification_method", "reason", "confirmation" ], "properties": { "outcome": { "type": "string", "enum": [ "approved", "rejected" ] }, "verification_method": { "type": "string", "enum": [ "official_source_manual", "document_review" ] }, "source_authority": { "type": "string", "maxLength": 512, "description": "Exact official authority name. Required for every official_source_manual decision; document_review cannot carry an external authority." }, "source_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Exact HTTPS official source URL. Required for every official_source_manual decision and forbidden for document_review." }, "reason": { "type": "string", "minLength": 3, "maxLength": 2000 }, "owner_reason_code": { "type": "string", "enum": [ "wrong_document_type", "identifier_mismatch", "holder_mismatch", "inactive_or_expired", "official_record_not_found", "qa_synthetic_fixture", "other" ], "description": "Controlled owner-visible rejection reason. New clients should always send it for rejection; omission maps to other only for legacy compatibility. official_record_not_found requires outcome=rejected, verification_method=official_source_manual, and valid official source fields." }, "observed_at": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "credential_expires_at": { "type": "string", "format": "date", "description": "Expiration date printed on the license. Required for an approved license submission and kept separate from Loppee's internal recheck valid_until." }, "verified_service_scope": { "type": "array", "items": { "type": "string" } }, "identifier_match": { "type": "boolean" }, "holder_name_match": { "type": "boolean" }, "active_or_good_standing": { "type": "boolean" }, "confirmation": { "type": "string", "enum": [ "APPROVE VERIFICATION", "REJECT VERIFICATION" ] } } } } } }, "responses": { "200": { "description": "Decide a Trust Model v3 manual-verification submission response", "content": { "application/json": { "schema": { "type": "object", "description": "Immutable audited manual-verification decision receipt.", "additionalProperties": true, "required": [ "schema_version", "status", "submission_id", "verification_method", "audit_event_id", "committed_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/v3/review-anomalies": { "get": { "tags": [ "Operations" ], "summary": "List Trust Model v3 review anomaly flags", "description": "List Trust Model v3 review anomaly flags. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List Trust Model v3 review anomaly flags response", "content": { "application/json": { "schema": { "type": "object", "description": "Private flag-only v3 review-anomaly moderation queue.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/v3/review-anomalies/{flag_id}/resolve": { "post": { "tags": [ "Operations" ], "summary": "Resolve a Trust Model v3 review anomaly flag", "description": "Resolve a Trust Model v3 review anomaly flag. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "flag_id", "in": "path", "required": true, "description": "flag id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "status", "resolution_note", "confirm" ], "properties": { "status": { "type": "string", "enum": [ "resolved", "ignored" ] }, "resolution_note": { "type": "string" }, "confirm": { "type": "string" } } } } } }, "responses": { "200": { "description": "Resolve a Trust Model v3 review anomaly flag response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited flag-only anomaly decision; review and ranking state remain unchanged.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/import-runs": { "get": { "tags": [ "Operations" ], "summary": "List import runs", "description": "List import runs. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "source query filter.", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "mode query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List import runs response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated import-run records.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/import-runs/{run_id}": { "get": { "tags": [ "Operations" ], "summary": "Get import run", "description": "Get import run. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "run_id", "in": "path", "required": true, "description": "run id path identifier.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Get import run response", "content": { "application/json": { "schema": { "type": "object", "description": "Import run, items, and events.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/quality-signals": { "get": { "tags": [ "Operations" ], "summary": "List data-quality signals", "description": "List data-quality signals. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "description": "severity query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List data-quality signals response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated data-quality signals.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/quality-signals/{signal_id}": { "get": { "tags": [ "Operations" ], "summary": "Get data-quality signal", "description": "Get data-quality signal. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "signal_id", "in": "path", "required": true, "description": "signal id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get data-quality signal response", "content": { "application/json": { "schema": { "type": "object", "description": "Quality signal with history and audit context.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Operations" ], "summary": "Update data-quality signal", "description": "Update data-quality signal. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "signal_id", "in": "path", "required": true, "description": "signal id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "status" ], "properties": { "status": { "type": "string" } } } } } }, "responses": { "200": { "description": "Update data-quality signal response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated quality signal.", "additionalProperties": true, "required": [ "schema_version", "status", "signal" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/duplicate-candidates": { "get": { "tags": [ "Operations" ], "summary": "List duplicate candidates", "description": "List duplicate candidates. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "min_confidence", "in": "query", "required": false, "description": "min confidence query filter.", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List duplicate candidates response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated duplicate candidates.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/duplicate-candidates/{candidate_id}": { "get": { "tags": [ "Operations" ], "summary": "Get duplicate candidate", "description": "Get duplicate candidate. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "candidate_id", "in": "path", "required": true, "description": "candidate id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get duplicate candidate response", "content": { "application/json": { "schema": { "type": "object", "description": "Duplicate candidate with business comparison and audit context.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Operations" ], "summary": "Review duplicate candidate", "description": "Review duplicate candidate. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "candidate_id", "in": "path", "required": true, "description": "candidate id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "status" ], "properties": { "status": { "type": "string" }, "review_notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Review duplicate candidate response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated duplicate candidate.", "additionalProperties": true, "required": [ "schema_version", "status", "candidate" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/duplicate-candidates/{candidate_id}/merge-dry-run": { "post": { "tags": [ "Operations" ], "summary": "Dry-run duplicate merge", "description": "Dry-run duplicate merge. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "candidate_id", "in": "path", "required": true, "description": "candidate id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "canonical_business_id": { "type": "string" }, "review_notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Dry-run duplicate merge response", "content": { "application/json": { "schema": { "type": "object", "description": "Auditable duplicate-merge dry run.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/bulk-jobs": { "get": { "tags": [ "Operations" ], "summary": "List bulk jobs", "description": "List bulk jobs. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "job_type", "in": "query", "required": false, "description": "job type query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List bulk jobs response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated bulk jobs.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/worker-tasks": { "get": { "tags": [ "Operations" ], "summary": "List worker tasks", "description": "List worker tasks. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List worker tasks response", "content": { "application/json": { "schema": { "type": "object", "description": "Durable Business Ops worker tasks.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/worker-tasks/{task_id}/control": { "post": { "tags": [ "Operations" ], "summary": "Control worker task", "description": "Control worker task. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "description": "task id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "action", "reason", "expected_version" ], "properties": { "action": { "type": "string" }, "reason": { "type": "string" }, "expected_version": { "type": "number" } } } } } }, "responses": { "200": { "description": "Control worker task response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited worker task control result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/job-events": { "get": { "tags": [ "Operations" ], "summary": "List bulk-job events", "description": "List bulk-job events. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "job_table", "in": "query", "required": false, "description": "job table query filter.", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "required": false, "description": "job id query filter.", "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "required": false, "description": "event type query filter.", "schema": { "type": "string" } }, { "name": "actor", "in": "query", "required": false, "description": "actor query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List bulk-job events response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated job audit events.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/bulk-jobs/{job_id}/apply": { "post": { "tags": [ "Operations" ], "summary": "Apply reviewed bulk job", "description": "Apply reviewed bulk job. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "confirm" ], "properties": { "confirm": { "type": "string" }, "limit": { "type": "number", "minimum": 1, "maximum": 1000 } } } } } }, "responses": { "200": { "description": "Apply reviewed bulk job response", "content": { "application/json": { "schema": { "type": "object", "description": "Applied bulk-job result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/bulk-jobs/{job_id}/enqueue": { "post": { "tags": [ "Operations" ], "summary": "Queue reviewed bulk job", "description": "Queue reviewed bulk job. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "confirm" ], "properties": { "confirm": { "type": "string" }, "chunk_size": { "type": "number", "minimum": 10, "maximum": 500 } } } } } }, "responses": { "200": { "description": "Queue reviewed bulk job response", "content": { "application/json": { "schema": { "type": "object", "description": "Queued durable worker task.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/bulk-jobs/{job_id}/rollback": { "post": { "tags": [ "Operations" ], "summary": "Rollback bulk job", "description": "Rollback bulk job. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "confirm" ], "properties": { "confirm": { "type": "string" }, "limit": { "type": "number", "minimum": 1, "maximum": 1000 } } } } } }, "responses": { "200": { "description": "Rollback bulk job response", "content": { "application/json": { "schema": { "type": "object", "description": "Rollback job result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/bulk-jobs/{job_id}": { "get": { "tags": [ "Operations" ], "summary": "Get bulk job", "description": "Get bulk job. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Get bulk job response", "content": { "application/json": { "schema": { "type": "object", "description": "Bulk job detail and paginated items.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/category-mappings": { "get": { "tags": [ "Operations" ], "summary": "List category mappings", "description": "List category mappings. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "description": "source query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "target_category", "in": "query", "required": false, "description": "target category query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List category mappings response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated source-category mappings.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Operations" ], "summary": "Create category mapping", "description": "Create category mapping. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "source", "source_category_slug", "target_category" ], "properties": { "source": { "type": "string" }, "source_category_slug": { "type": "string" }, "target_category": { "type": "string" }, "status": { "type": "string" }, "confidence": { "type": "number" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Create category mapping response", "content": { "application/json": { "schema": { "type": "object", "description": "Created category mapping.", "additionalProperties": true, "required": [ "schema_version", "status", "mapping" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/category-mappings/{mapping_id}": { "patch": { "tags": [ "Operations" ], "summary": "Update category mapping", "description": "Update category mapping. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "mapping_id", "in": "path", "required": true, "description": "mapping id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "minProperties": 1, "properties": { "target_category": { "type": "string" }, "status": { "type": "string" }, "confidence": { "type": "number" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Update category mapping response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated category mapping.", "additionalProperties": true, "required": [ "schema_version", "status", "mapping" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/quality-scan/dry-run": { "post": { "tags": [ "Operations" ], "summary": "Create quality-scan dry run", "description": "Create quality-scan dry run. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "state": { "type": "string" }, "limit": { "type": "number" } } } } } }, "responses": { "200": { "description": "Create quality-scan dry run response", "content": { "application/json": { "schema": { "type": "object", "description": "Quality-scan dry-run job.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/ops/category-remap/dry-run": { "post": { "tags": [ "Operations" ], "summary": "Create category-remap dry run", "description": "Create category-remap dry run. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "source": { "type": "string" }, "source_category_slug": { "type": "string" }, "target_category": { "type": "string" }, "version": { "type": "string" }, "limit": { "type": "number" } } } } } }, "responses": { "200": { "description": "Create category-remap dry run response", "content": { "application/json": { "schema": { "type": "object", "description": "Category-remap dry-run job.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/customers": { "get": { "tags": [ "Operations" ], "summary": "List customer accounts", "description": "List customer accounts. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "category query filter.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "state query filter.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "sort query filter.", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "dir query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List customer accounts response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated administrative customer records.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/service-accounts": { "get": { "tags": [ "Operations" ], "summary": "List service accounts", "description": "List service accounts. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "account_type", "in": "query", "required": false, "description": "account type query filter.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "sort query filter.", "schema": { "type": "string" } }, { "name": "dir", "in": "query", "required": false, "description": "dir query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List service accounts response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated administrative service-account records.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/service-accounts/{account_id}/status": { "post": { "tags": [ "Operations" ], "summary": "Update service-account status", "description": "Update service-account status. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "account id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "needs_review", "blocked" ] } } } } } }, "responses": { "200": { "description": "Update service-account status response", "content": { "application/json": { "schema": { "type": "object", "description": "Service-account status update.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/service-accounts/{account_id}": { "get": { "tags": [ "Operations" ], "summary": "Get service account", "description": "Get service account. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "account_id", "in": "path", "required": true, "description": "account id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get service account response", "content": { "application/json": { "schema": { "type": "object", "description": "Administrative service-account detail with masked credentials.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/activity": { "get": { "tags": [ "Operations" ], "summary": "List admin activity", "description": "List admin activity. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "action query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List admin activity response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated administrative audit activity.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/analytics": { "get": { "tags": [ "Operations" ], "summary": "Get admin analytics", "description": "Get admin analytics. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "days query filter.", "schema": { "type": "number" } }, { "name": "range", "in": "query", "required": false, "description": "range query filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get admin analytics response", "content": { "application/json": { "schema": { "type": "object", "description": "Administrative analytics aggregate.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/deals": { "get": { "tags": [ "Operations" ], "summary": "List deals for moderation", "description": "List deals for moderation. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List deals for moderation response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated deal-moderation records.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/deals/{deal_id}/moderate": { "post": { "tags": [ "Operations" ], "summary": "Moderate deal", "description": "Moderate deal. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "deal_id", "in": "path", "required": true, "description": "deal id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "action" ], "properties": { "action": { "type": "string" } } } } } }, "responses": { "200": { "description": "Moderate deal response", "content": { "application/json": { "schema": { "type": "object", "description": "Deal moderation result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/media/{asset_id}/remove": { "post": { "tags": [ "Operations" ], "summary": "Remove public business media", "description": "Remove public business media. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "description": "asset id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Remove public business media response", "content": { "application/json": { "schema": { "type": "object", "description": "Moderated media removal result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team": { "get": { "tags": [ "Operations" ], "summary": "Get admin team", "description": "Get admin team. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "responses": { "200": { "description": "Get admin team response", "content": { "application/json": { "schema": { "type": "object", "description": "Team members, pending invites, and masked team-agent records.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/invites": { "post": { "tags": [ "Operations" ], "summary": "Invite admin team member", "description": "Invite admin team member. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string" } } } } } }, "responses": { "200": { "description": "Invite admin team member response", "content": { "application/json": { "schema": { "type": "object", "description": "Created team invite.", "additionalProperties": true, "required": [ "status", "invite", "email_sent" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents": { "post": { "tags": [ "Operations" ], "summary": "Connect external admin team agent", "description": "Connect external admin team agent. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "name", "role" ], "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "confirm_admin": { "type": "boolean" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Connect external admin team agent response", "content": { "application/json": { "schema": { "type": "object", "description": "Connected an externally supplied team agent; Loppee returns only the scoped raw key once.", "additionalProperties": true, "required": [ "status", "external_agent_access", "agent", "raw_key", "one_time_display", "mcp_endpoint" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/access": { "post": { "tags": [ "Operations" ], "summary": "Change admin team-agent access", "description": "Change admin team-agent access. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "role", "reason", "confirm" ], "properties": { "role": { "type": "string" }, "reason": { "type": "string" }, "confirm": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Change admin team-agent access response", "content": { "application/json": { "schema": { "type": "object", "description": "Changed the team-agent role, revoked the old key, and returned the replacement raw key once.", "additionalProperties": true, "required": [ "status", "external_agent_access", "agent", "raw_key", "one_time_display", "mcp_endpoint" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/scope": { "post": { "tags": [ "Operations" ], "summary": "Replace admin team-agent key scope", "description": "Replace admin team-agent key scope. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "expected_key_id", "expected_allowed_actions", "allowed_actions", "reason", "confirm" ], "properties": { "expected_key_id": { "type": "string" }, "expected_allowed_actions": { "type": "array", "items": { "type": "string" } }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" }, "confirm": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Replace admin team-agent key scope response", "content": { "application/json": { "schema": { "type": "object", "description": "Atomically replaced the exact team-agent key scope and wrote an audit receipt.", "additionalProperties": true, "required": [ "status", "account_id", "key_id", "allowed_actions", "audit_id", "changed_at" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/rotate-key": { "post": { "tags": [ "Operations" ], "summary": "Rotate admin team-agent key", "description": "Rotate admin team-agent key. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate admin team-agent key response", "content": { "application/json": { "schema": { "type": "object", "description": "Rotated the external team-agent credential; raw key is returned once.", "additionalProperties": true, "required": [ "status", "external_agent_access", "agent", "raw_key", "one_time_display", "mcp_endpoint" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/disable": { "post": { "tags": [ "Operations" ], "summary": "Disable admin team agent", "description": "Disable admin team agent. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disable admin team agent response", "content": { "application/json": { "schema": { "type": "object", "description": "Disabled team agent and revoked keys.", "additionalProperties": true, "required": [ "status" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/webhook": { "get": { "tags": [ "Operations" ], "summary": "Get back-office agent webhook", "description": "Human-admin manage_team view of the signed HTTPS wake-up endpoint for one active external back-office agent. The response never reveals the one-time signing secret or the agent API key.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get back-office agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] } } } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Operations" ], "summary": "Register back-office agent webhook", "description": "Human-admin-only recent-AAL2 manage_team registration of a provider-neutral HTTPS wake-up receiver for one active back-office agent credential. Loppee sends reference-only admin.verification_submission.created events; the receiver verifies the HMAC, then uses its separately scoped Loppee API/MCP key for authorized queue reads or decisions. Re-registering replaces the endpoint and rotates the signing secret, which is returned once.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048, "description": "Public HTTPS receiver operated by the connecting principal or its agent runtime. Credentials in the URL and private-network destinations are rejected." } } } } } }, "responses": { "200": { "description": "Register back-office agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint", "signing_secret", "one_time_display", "delivery_contract" ], "properties": { "status": { "type": "string", "enum": [ "registered", "rotated" ] }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "signing_secret": { "type": "string", "pattern": "^loppee_whsec_", "minLength": 32 }, "one_time_display": { "const": true }, "delivery_contract": { "type": "object", "additionalProperties": false, "required": [ "version", "authentication", "payload_mode" ], "properties": { "version": { "const": "loppee.webhook.v1" }, "authentication": { "const": "hmac_sha256" }, "payload_mode": { "const": "reference_only" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/webhook/rotate-secret": { "post": { "tags": [ "Operations" ], "summary": "Rotate back-office agent webhook secret", "description": "Human-admin-only recent-AAL2 manage_team rotation of the HMAC signing secret. The replacement secret is returned once; no back-office authority changes.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate back-office agent webhook secret response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint", "signing_secret", "one_time_display", "delivery_contract" ], "properties": { "status": { "type": "string", "enum": [ "registered", "rotated" ] }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "signing_secret": { "type": "string", "pattern": "^loppee_whsec_", "minLength": 32 }, "one_time_display": { "const": true }, "delivery_contract": { "type": "object", "additionalProperties": false, "required": [ "version", "authentication", "payload_mode" ], "properties": { "version": { "const": "loppee.webhook.v1" }, "authentication": { "const": "hmac_sha256" }, "payload_mode": { "const": "reference_only" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/webhook/disable": { "post": { "tags": [ "Operations" ], "summary": "Disable back-office agent webhook", "description": "Human-admin-only recent-AAL2 manage_team disablement of wake-up deliveries. Disabling the webhook does not change the external agent's separately scoped permissions.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disable back-office agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "endpoint" ], "properties": { "status": { "const": "disabled" }, "endpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "connection_kind", "account_id", "credential_id", "business_id", "endpoint_url", "event_types", "enabled", "disabled_reason", "failure_count", "last_delivery_at", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "connection_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string" }, "credential_id": { "type": "string" }, "business_id": { "type": [ "string", "null" ] }, "endpoint_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "event_types": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created" ] } }, "enabled": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "failure_count": { "type": "integer", "minimum": 0 }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/agents/{agent_id}/webhook/test": { "post": { "tags": [ "Operations" ], "summary": "Test back-office agent webhook", "description": "Human-admin-only recent-AAL2 manage_team enqueue of a signed agent.webhook.test wake-up event through the live signing and delivery path. It is receipt-only: the receiver validates the signature/timestamp and returns 2xx without fetching a resource.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "agent id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Test back-office agent webhook response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "event_id", "endpoint_id" ], "properties": { "status": { "const": "queued" }, "event_id": { "type": "string" }, "endpoint_id": { "type": "string" } } } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/invites/{invite_id}/revoke": { "post": { "tags": [ "Operations" ], "summary": "Revoke admin team invite", "description": "Revoke admin team invite. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "invite_id", "in": "path", "required": true, "description": "invite id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoke admin team invite response", "content": { "application/json": { "schema": { "type": "object", "description": "Revoked team invite.", "additionalProperties": true, "required": [ "status", "invite_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/members/{user_id}/remove": { "post": { "tags": [ "Operations" ], "summary": "Remove admin team member", "description": "Remove admin team member. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "user id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Remove admin team member response", "content": { "application/json": { "schema": { "type": "object", "description": "Removed admin member.", "additionalProperties": true, "required": [ "status", "user_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/team/members/{user_id}": { "post": { "tags": [ "Operations" ], "summary": "Update admin team member", "description": "Update admin team member. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "description": "user id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "minProperties": 1, "properties": { "role": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } } } } }, "responses": { "200": { "description": "Update admin team member response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated admin member.", "additionalProperties": true, "required": [ "status", "member" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/reviews/reports": { "get": { "tags": [ "Operations" ], "summary": "List review reports", "description": "List review reports. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "business_id", "in": "query", "required": false, "description": "business id query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } }, { "name": "q", "in": "query", "required": false, "description": "q query filter.", "schema": { "type": "string" } }, { "name": "rating", "in": "query", "required": false, "description": "rating query filter.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "date from query filter.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "date to query filter.", "schema": { "type": "string" } }, { "name": "include_metrics", "in": "query", "required": false, "description": "include metrics query filter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List review reports response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated review-report moderation queue.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/reviews/reports/bulk-dismiss": { "post": { "tags": [ "Operations" ], "summary": "Bulk dismiss review reports", "description": "Bulk dismiss review reports. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "report_ids" ], "properties": { "report_ids": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Bulk dismiss review reports response", "content": { "application/json": { "schema": { "type": "object", "description": "Bulk report-dismissal result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/access-contexts": { "post": { "tags": [ "Operations" ], "summary": "Enter an administrative resource context", "description": "Creates a 15-minute principal-bound authority for one explicit Business Messages or Business Jobs workspace. The raw token is returned once and must be held only in memory. Jobs applicant detail and resume capabilities are human-only.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "context_type", "context_id", "scope", "purpose_code" ], "properties": { "context_type": { "type": "string", "enum": [ "business" ] }, "context_id": { "type": "string" }, "scope": { "type": "string", "enum": [ "messages", "jobs" ] }, "purpose_code": { "type": "string", "enum": [ "abuse_report", "support_request", "policy_check", "legal_request" ] }, "related_case_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Enter an administrative resource context response", "content": { "application/json": { "schema": { "type": "object", "description": "One-time access-context token and expiry.", "additionalProperties": true, "required": [ "access_context" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/access-contexts/{access_context_id}": { "delete": { "tags": [ "Operations" ], "summary": "Exit an administrative resource context", "description": "Idempotently revokes one context owned by the current principal. The context id is retained only in volatile memory so a failed or ambiguous exit can be retried without retaining the raw context token.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "access_context_id", "in": "path", "required": true, "description": "access context id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exit an administrative resource context response", "content": { "application/json": { "schema": { "type": "object", "description": "Revoked access context.", "additionalProperties": true, "required": [ "status", "access_context_id" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/jobs": { "get": { "tags": [ "Operations" ], "summary": "List one business's job posts", "description": "Lists job-posting metadata only for the selected Business workspace. Applicant data is excluded and the opaque Jobs context must match the path business.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "search query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List one business's job posts response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated, business-scoped job-posting metadata.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/jobs/{job_id}/close": { "post": { "tags": [ "Operations" ], "summary": "Close one business job post", "description": "Closes a job only after the Jobs context, selected business, and job ownership all match. The action is audited and requires the human-only close capability.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "job_id", "in": "path", "required": true, "description": "job id path identifier.", "schema": { "type": "string" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "reason" ], "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Close one business job post response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited, business-scoped job-post closure result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/job-applications": { "get": { "tags": [ "Operations" ], "summary": "List one business's job applications", "description": "Returns a privacy-minimized application list for the selected business. Applicant email, cover note, resume metadata, and resume access are excluded from this collection response. Human-only application-list authority is required.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "job_id", "in": "query", "required": false, "description": "job id query filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List one business's job applications response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated, privacy-minimized business job applications.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/job-applications/{application_id}": { "get": { "tags": [ "Operations" ], "summary": "Get one business job application", "description": "Returns audited private application detail only after the human principal, Jobs context, selected business, application, and owning job all match. It does not issue a resume URL.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "application_id", "in": "path", "required": true, "description": "application id path identifier.", "schema": { "type": "string" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get one business job application response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited, business-scoped private application detail.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/job-applications/{application_id}/resume-url": { "post": { "tags": [ "Operations" ], "summary": "Create one business application resume URL", "description": "Issues a short-lived signed URL only to a human principal with the exact resume-read capability after business ownership, current scan-clean authority, removal state, and storage authority are revalidated.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "application_id", "in": "path", "required": true, "description": "application id path identifier.", "schema": { "type": "string" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Create one business application resume URL response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited short-lived resume URL result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/messages": { "get": { "tags": [ "Operations" ], "summary": "List one business's message threads", "description": "List one business's message threads. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "status query filter.", "schema": { "type": "string" } }, { "name": "account_id", "in": "query", "required": false, "description": "account id query filter.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "q query filter.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "date from query filter.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "date to query filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "limit query filter.", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "offset query filter.", "schema": { "type": "number" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List one business's message threads response", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated, body-free message metadata for the selected business.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/messages/{thread_id}": { "get": { "tags": [ "Operations" ], "summary": "Get one business message thread", "description": "Get one business message thread. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "thread_id", "in": "path", "required": true, "description": "thread id path identifier.", "schema": { "type": "string" } }, { "name": "reason", "in": "query", "required": true, "description": "reason query filter.", "schema": { "type": "string" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get one business message thread response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited message thread detail.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/businesses/{business_id}/messages/{thread_id}/moderate": { "post": { "tags": [ "Operations" ], "summary": "Moderate one business message thread", "description": "Moderate one business message thread. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "business id path identifier.", "schema": { "type": "string" } }, { "name": "thread_id", "in": "path", "required": true, "description": "thread id path identifier.", "schema": { "type": "string" } }, { "name": "X-Loppee-Admin-Context", "in": "header", "required": true, "description": "Opaque, short-lived authority returned by POST /v1/admin/access-contexts for this exact Business workspace.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "action" ], "properties": { "action": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Moderate one business message thread response", "content": { "application/json": { "schema": { "type": "object", "description": "Audited, business-scoped message moderation result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/reviews/{review_id}/moderate": { "post": { "tags": [ "Operations" ], "summary": "Moderate review", "description": "Moderate review. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] }, { "AgentApiKey": [] } ], "parameters": [ { "name": "review_id", "in": "path", "required": true, "description": "review id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "action" ], "properties": { "action": { "type": "string" }, "reason_category": { "type": "string" }, "reason_detail": { "type": "string" }, "reason": { "type": "string" }, "report_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Moderate review response", "content": { "application/json": { "schema": { "type": "object", "description": "Review moderation result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/coupons": { "get": { "tags": [ "Operations" ], "summary": "List subscription coupons", "description": "List subscription coupons. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "responses": { "200": { "description": "List subscription coupons response", "content": { "application/json": { "schema": { "type": "object", "description": "Administrative coupon records and redemption counts.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Operations" ], "summary": "Create subscription coupon", "description": "Create subscription coupon. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "code", "discount_type" ], "properties": { "code": { "type": "string" }, "discount_type": { "type": "string", "enum": [ "percent", "fixed" ] }, "percent_off": { "type": "number", "minimum": 1, "maximum": 100 }, "amount_off_cents": { "type": "number", "minimum": 1 }, "duration": { "type": "string", "enum": [ "once", "repeating", "forever" ] }, "duration_in_months": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 24 }, "applies_to_tier": { "type": [ "string", "null" ] }, "applies_to_period": { "type": "string", "enum": [ "all", "monthly", "annual" ] }, "max_redemptions": { "type": [ "integer", "null" ], "minimum": 1 }, "per_customer_limit": { "type": "number", "minimum": 1 }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Create subscription coupon response", "content": { "application/json": { "schema": { "type": "object", "description": "Created coupon. Discounts affect price only.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/coupons/{coupon_id}": { "post": { "tags": [ "Operations" ], "summary": "Update subscription coupon", "description": "Update subscription coupon. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "coupon_id", "in": "path", "required": true, "description": "coupon id path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "minProperties": 1, "properties": { "active": { "type": "boolean" }, "note": { "type": "string" }, "applies_to_tier": { "type": [ "string", "null" ] }, "applies_to_period": { "type": "string", "enum": [ "all", "monthly", "annual" ] }, "max_redemptions": { "type": [ "integer", "null" ], "minimum": 1 }, "per_customer_limit": { "type": "number", "minimum": 1 }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Update subscription coupon response", "content": { "application/json": { "schema": { "type": "object", "description": "Updated coupon; immutable commercial identity fields cannot change.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Operations" ], "summary": "Archive subscription promotion", "description": "Archive subscription promotion. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "coupon_id", "in": "path", "required": true, "description": "coupon id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Archive subscription promotion response", "content": { "application/json": { "schema": { "type": "object", "description": "Archived promotion. Redemption and accounting history is retained; new use is blocked.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/coupons/preview": { "post": { "tags": [ "Business Owner" ], "summary": "Preview subscription coupon", "description": "Preview subscription coupon. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "code", "tier" ], "properties": { "business_id": { "type": "string" }, "code": { "type": "string" }, "tier": { "type": "string" }, "period": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Preview subscription coupon response", "content": { "application/json": { "schema": { "type": "object", "description": "Coupon eligibility and discounted price preview.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/owner/coupons/checkout": { "post": { "tags": [ "Business Owner" ], "summary": "Checkout with subscription coupon", "description": "Checkout with subscription coupon. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseOwnerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "code", "tier" ], "properties": { "business_id": { "type": "string" }, "code": { "type": "string" }, "tier": { "type": "string" }, "period": { "type": "string", "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Checkout with subscription coupon response", "content": { "application/json": { "schema": { "type": "object", "description": "Discounted checkout session.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/pricing-content": { "get": { "tags": [ "Operations" ], "summary": "Get pricing-content editor state", "description": "Get pricing-content editor state. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "responses": { "200": { "description": "Get pricing-content editor state response", "content": { "application/json": { "schema": { "type": "object", "description": "Pricing draft, published revision, defaults, and Stripe sync checklist.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/pricing-content/draft": { "post": { "tags": [ "Operations" ], "summary": "Save pricing-content draft", "description": "Save pricing-content draft. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "config" ], "properties": { "config": { "type": "object", "description": "Complete validated pricing configuration.", "additionalProperties": true }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Save pricing-content draft response", "content": { "application/json": { "schema": { "type": "object", "description": "Saved pricing draft.", "additionalProperties": true, "required": [ "draft" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/pricing-content/publish": { "post": { "tags": [ "Operations" ], "summary": "Publish pricing-content draft", "description": "Publish pricing-content draft. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Publish pricing-content draft response", "content": { "application/json": { "schema": { "type": "object", "description": "Published pricing revision.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/pricing-content/discard-draft": { "post": { "tags": [ "Operations" ], "summary": "Discard pricing-content draft", "description": "Discard pricing-content draft. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "responses": { "200": { "description": "Discard pricing-content draft response", "content": { "application/json": { "schema": { "type": "object", "description": "Pricing draft discard result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/content": { "get": { "tags": [ "Operations" ], "summary": "Get site-content editor state", "description": "Get site-content editor state. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "responses": { "200": { "description": "Get site-content editor state response", "content": { "application/json": { "schema": { "type": "object", "description": "Editable content blocks, defaults, revisions, and neutrality metadata.", "additionalProperties": true } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/content/media": { "get": { "tags": [ "Operations" ], "summary": "List site-content media", "description": "List site-content media. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "responses": { "200": { "description": "List site-content media response", "content": { "application/json": { "schema": { "type": "object", "description": "Current site-content media records.", "additionalProperties": true, "required": [ "media" ] } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Operations" ], "summary": "Upload site-content media", "description": "Upload site-content media. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "kind", "file_name", "content_type", "size_bytes", "data_base64" ], "properties": { "kind": { "type": "string", "enum": [ "image", "video" ] }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number", "minimum": 1 }, "data_base64": { "type": "string" }, "alt": { "type": "string" }, "caption": { "type": "string" }, "width": { "type": "number", "minimum": 1 }, "height": { "type": "number", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Upload site-content media response", "content": { "application/json": { "schema": { "type": "object", "description": "Uploaded site-content media.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/content/media/{media_id}/delete": { "post": { "tags": [ "Operations" ], "summary": "Delete site-content media", "description": "Delete site-content media. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "media_id", "in": "path", "required": true, "description": "media id path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete site-content media response", "content": { "application/json": { "schema": { "type": "object", "description": "Soft-deleted site-content media.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/content/blocks/{block_key}/draft": { "post": { "tags": [ "Operations" ], "summary": "Save content-block draft", "description": "Save content-block draft. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "block_key", "in": "path", "required": true, "description": "block key path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "fields" ], "properties": { "fields": { "type": "object", "description": "Validated fields for this fixed content-block type.", "additionalProperties": true }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Save content-block draft response", "content": { "application/json": { "schema": { "type": "object", "description": "Saved content-block draft.", "additionalProperties": true, "required": [ "draft" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/content/blocks/{block_key}/publish": { "post": { "tags": [ "Operations" ], "summary": "Publish content-block draft", "description": "Publish content-block draft. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "block_key", "in": "path", "required": true, "description": "block key path identifier.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Publish content-block draft response", "content": { "application/json": { "schema": { "type": "object", "description": "Published content block.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/content/blocks/{block_key}/discard-draft": { "post": { "tags": [ "Operations" ], "summary": "Discard content-block draft", "description": "Discard content-block draft. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "block_key", "in": "path", "required": true, "description": "block key path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Discard content-block draft response", "content": { "application/json": { "schema": { "type": "object", "description": "Content-block draft discard result.", "additionalProperties": true } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/admin/content/blocks/{block_key}/revert": { "post": { "tags": [ "Operations" ], "summary": "Revert content block to default", "description": "Revert content block to default. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [ { "SupabaseAdminBearer": [] } ], "parameters": [ { "name": "block_key", "in": "path", "required": true, "description": "block key path identifier.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revert content block to default response", "content": { "application/json": { "schema": { "type": "object", "description": "Content-block default reversion result.", "additionalProperties": true, "required": [ "reverted" ] } } } }, "400": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/schemas/{schema_name}": { "get": { "tags": [ "Trust Cards" ], "summary": "Get agent JSON Schema", "description": "Get agent JSON Schema. The response is scoped and validated by the runtime repository; unknown or unauthorized resources use the canonical error envelope.", "security": [], "parameters": [ { "name": "schema_name", "in": "path", "required": true, "description": "schema name path identifier.", "schema": { "type": "string", "pattern": "^[^/]+\\.schema\\.json$" } } ], "responses": { "200": { "description": "Get agent JSON Schema response", "content": { "application/json": { "schema": { "type": "object", "description": "Requested published JSON Schema document.", "additionalProperties": true } } } }, "404": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "RateLimitError", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "ErrorResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/account/location-handoffs": { "post": { "operationId": "createLocationHandoff", "summary": "Ask the customer to approve precise location", "description": "Creates a provider-neutral, short-lived location request. Current location is iPhone-app-only: a successful current request returns poll_location_handoff or open_loppee_phone_app and never returns location_url. If phone authority is unavailable, creation fails closed; caller coordinates, provider IP, computer/browser location, and host metadata are never substitutes. For poll_location_handoff, tell the customer to approve in the Loppee iPhone app, wait poll_after_seconds, and poll once. For open_loppee_phone_app, instruct: Open Loppee on iPhone → Account → My AI agents → Pending location requests. A connected-assistant current-location handoff is organic-only: no Sponsored ordering or labels, exposure accounting, or recommendation attribution. A destination request may return a secure browser location_url. The agent receives readiness and normal business results, never an address or coordinates.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "responses": { "201": { "description": "Consent link created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationHandoffCreateResponse" } } } }, "403": { "description": "A consumer personal-agent key is required." }, "429": { "description": "Too many active or recently created requests." }, "503": { "description": "The registered Loppee iPhone authority is unavailable; no browser, provider-IP, metadata, or caller-coordinate fallback is permitted." } } } }, "/v1/account/location-handoffs/{handoff_id}": { "get": { "operationId": "getLocationHandoffStatus", "summary": "Check a customer location request", "description": "Returns only lifecycle status, expiry, and remaining bounded uses. It never returns latitude, longitude, an address, or exact accuracy.", "security": [ { "AgentApiKey": [] }, { "AgentBearer": [] } ], "parameters": [ { "name": "handoff_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current request status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationHandoffStatusResponse" } } } }, "404": { "description": "Unknown, foreign, revoked, or unavailable request." } } } }, "/v1/account/location-proofs": { "post": { "operationId": "createCustomerLocationProof", "summary": "Create a private customer location proof", "description": "Accepts one fresh, consented device-location reading from a signed-in Loppee customer and returns only an opaque short-lived proof id. Exact coordinates are encrypted, never returned, and never placed in a search URL.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLocationProofRequest" } } } }, "responses": { "201": { "description": "Private location proof created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLocationProofResponse" } } } }, "400": { "description": "The location reading is stale, outside supported US bounds, or less accurate than 500 metres." }, "401": { "description": "A valid signed-in customer session is required." }, "403": { "description": "The session is not an active customer account." }, "429": { "description": "Too many location-proof requests." } } } }, "/v1/account/destination-location-proofs": { "post": { "operationId": "createCustomerDestinationLocationProof", "summary": "Validate a customer-selected service destination", "description": "First-party customer/mobile route. Accepts one real US service address in the POST body, validates it server-side with Google Address Validation, and returns only an opaque short-lived destination proof. It never returns the submitted or normalized address, coordinates, or exact accuracy. Google Maps attribution must remain visible in the first-party destination UI.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationLocationProofRequest" } } } }, "responses": { "201": { "description": "Private destination proof created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationLocationProofResponse" } } } }, "400": { "description": "The address is invalid, unsupported, incomplete, ambiguous, or cannot safely mint premise-level authority." }, "401": { "description": "A valid signed-in customer session is required." }, "403": { "description": "The session is not an active customer account." }, "409": { "description": "Premise-proximity confirmation is required, or its opaque confirmation token is invalid, expired, replayed, or bound to another authority/address/provider anchor." }, "429": { "description": "Too many destination-proof requests." }, "503": { "description": "Server-side address validation or destination authority storage is unavailable." } } } }, "/v1/account/destination-address-suggestions": { "post": { "operationId": "suggestCustomerDestinationAddresses", "summary": "Suggest service addresses for a signed-in customer", "description": "First-party customer/mobile and authenticated handoff UI route; not an external-agent API. After four normalized characters, it forwards only the partial input through Loppee to Google Places Autocomplete (New) and returns at most five display-text-only suggestions. Loppee does not retain the partial input or suggestion list. Provider ids, coordinates, address metadata, and autocomplete session tokens are never returned. The UI must keep manual entry available and show Google Maps attribution with the suggestions.", "security": [ { "SupabaseCustomerBearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationAddressSuggestionsRequest" } } } }, "responses": { "200": { "description": "Display-only address suggestions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationAddressSuggestionsResponse" } } } }, "400": { "description": "The partial input is shorter than four normalized characters, too long, or malformed." }, "401": { "description": "A valid signed-in customer session is required." }, "403": { "description": "The session is not an active customer account or an API/agent key was supplied." }, "404": { "description": "Destination address suggestions are disabled on this deployment." }, "429": { "description": "Too many address-suggestion requests." }, "503": { "description": "Google Places Autocomplete (New) is unavailable or returned an invalid response." } } } }, "/v1/account/location-proofs/{location_proof_id}": { "delete": { "operationId": "revokeCustomerLocationProof", "summary": "Clear a private customer location proof", "description": "Revokes and cryptographically scrubs one proof belonging to the signed-in customer. It never returns coordinates.", "security": [ { "SupabaseCustomerBearer": [] } ], "parameters": [ { "name": "location_proof_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Proof revoked or already terminal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerLocationProofRevocationResponse" } } } }, "401": { "description": "A valid signed-in customer session is required." }, "404": { "description": "Unknown, foreign, or unavailable proof." } } } }, "/v1/location-proofs": { "post": { "operationId": "createAnonymousBrowserLocationProof", "summary": "Create a private anonymous browser location proof", "description": "Browser-only first-party UX route; not an external-agent or native-app API. After a visible user gesture and browser permission, accepts one fresh device-location reading from a same-origin Loppee fetch whose point is plausibly near the server-resolved client-IP city. Returns only an opaque short-lived proof id and binds it to a Secure HttpOnly SameSite=Strict cookie. Coordinates are encrypted and never returned or placed in a search URL. This is abuse-resistant consented location input, not device or coordinate attestation.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousLocationProofRequest" } } } }, "responses": { "201": { "description": "Anonymous browser location proof created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousLocationProofResponse" } } } }, "400": { "description": "The reading is stale, unsupported, or insufficiently accurate." }, "403": { "description": "The request is not a same-origin browser flow, has credentials, has no trustworthy coarse-IP result, or is implausibly far from that result." }, "429": { "description": "Too many anonymous location-proof requests." } } } }, "/v1/destination-location-proofs": { "post": { "operationId": "createAnonymousDestinationLocationProof", "summary": "Validate an anonymous browser service destination", "description": "Same-origin first-party browser route. Accepts one real US service address in the POST body, validates it server-side with Google Address Validation, and returns only an opaque short-lived proof bound to a Secure HttpOnly SameSite=Strict cookie. It never returns the submitted or normalized address, coordinates, or exact accuracy. Google Maps attribution must remain visible in the first-party destination UI.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationLocationProofRequest" } } } }, "responses": { "201": { "description": "Anonymous destination proof created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationLocationProofResponse" } } } }, "400": { "description": "The address is invalid, unsupported, incomplete, ambiguous, or cannot safely mint premise-level authority." }, "403": { "description": "The request is not an allowed same-origin browser flow." }, "409": { "description": "Premise-proximity confirmation is required, or its opaque confirmation token is invalid, expired, replayed, or bound to another browser/address/provider anchor." }, "429": { "description": "Too many anonymous destination-proof requests." }, "503": { "description": "Server-side address validation or destination authority storage is unavailable." } } } }, "/v1/destination-address-suggestions": { "post": { "operationId": "suggestAnonymousDestinationAddresses", "summary": "Suggest service addresses in the first-party browser UI", "description": "Same-origin first-party browser UI route; not an external-agent or native-app API. After four normalized characters, it forwards only the partial input through Loppee to Google Places Autocomplete (New) and returns at most five display-text-only suggestions. Loppee does not retain the partial input or suggestion list. Provider ids, coordinates, address metadata, and autocomplete session tokens are never returned. The UI must keep manual entry available and show Google Maps attribution with the suggestions.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationAddressSuggestionsRequest" } } } }, "responses": { "200": { "description": "Display-only address suggestions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationAddressSuggestionsResponse" } } } }, "400": { "description": "The partial input is shorter than four normalized characters, too long, or malformed." }, "403": { "description": "The request is not an allowed same-origin browser flow." }, "404": { "description": "Destination address suggestions are disabled on this deployment." }, "429": { "description": "Too many address-suggestion requests." }, "503": { "description": "Google Places Autocomplete (New) is unavailable or returned an invalid response." } } } }, "/v1/location-proofs/{location_proof_id}": { "delete": { "operationId": "revokeAnonymousBrowserLocationProof", "summary": "Clear an anonymous browser location proof", "description": "Browser-only first-party UX route; not an external-agent or native-app API. Revokes and cryptographically scrubs the cookie-bound proof. A copied id without the original browser cookie is unusable. Coordinates are never returned.", "security": [], "parameters": [ { "name": "location_proof_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Proof revoked or already terminal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnonymousLocationProofRevocationResponse" } } } }, "404": { "description": "Unknown, stolen, expired, or unavailable proof." } } } } }, "components": { "securitySchemes": { "AgentApiKey": { "type": "apiKey", "in": "header", "name": "X-LOPPEE-API-Key", "description": "Scoped agent key. Admin-agent requests are authorized only by the key's explicit allowed_actions; admin-agent keys cannot delete users or agents." }, "AgentBearer": { "type": "http", "scheme": "bearer", "description": "Bearer form of a scoped agent key for non-admin agent workflows. Admin routes deliberately require X-LOPPEE-API-Key for agent keys so Authorization remains unambiguous for human Supabase admin sessions." }, "SupabaseAdminBearer": { "type": "http", "scheme": "bearer", "description": "Supabase Auth access token with MFA/AAL2 for a user listed in admin_users." }, "SupabaseSessionBearer": { "type": "http", "scheme": "bearer", "description": "Signature-verified Supabase Auth access token used only to resolve the session's mutually exclusive customer, owner, or admin role. Role-specific operations still enforce their own account and AAL2 requirements." }, "SupabaseCustomerBearer": { "type": "http", "scheme": "bearer", "description": "Signature-verified Supabase Auth access token for an active customer account. AAL2 is operation-specific: endpoints that explicitly require step-up reject AAL1; ordinary review MFA follows deployment policy." }, "SupabaseOwnerBearer": { "type": "http", "scheme": "bearer", "description": "Supabase Auth access token with MFA/AAL2 for an active owner account. Customer/admin role overlap is rejected by runtime and database role-exclusivity guards." }, "StripeSignature": { "type": "apiKey", "in": "header", "name": "Stripe-Signature", "description": "Stripe webhook signature verified against the configured endpoint secret before any mutation." }, "OwnerEvidenceScanCallback": { "type": "apiKey", "in": "header", "name": "X-Loppee-Scan-Callback-Token", "description": "Single-intent HMAC callback authority supplied only to the private Render Workflow task." }, "JobResumeScanCallback": { "type": "apiKey", "in": "header", "name": "X-Loppee-Job-Resume-Scan-Callback-Token", "description": "Dedicated single-intent callback authority supplied only to the private job-resume scanner task; it is bound to the immutable scan authority and exact file fingerprint." }, "ExternalAgentWebhookHmac": { "type": "apiKey", "in": "header", "name": "X-Webhook-Signature-V2", "description": "Lowercase hexadecimal HMAC-SHA256 of '.' using the one-time endpoint signing secret. The signing secret authenticates this delivery only and grants no Loppee API authority." } }, "schemas": { "HealthResponse": { "type": "object", "additionalProperties": false, "required": [ "ok", "service", "version", "contract_version", "trust_model_version", "business_review_access", "external_agent_webhooks_enabled", "external_agent_webhooks", "location_handoff", "location_choices", "ios_app_attest_anonymous_location", "agent_phone_location_bridge", "mobile_push", "sponsored_ordering", "build_sha" ], "properties": { "ok": { "const": true }, "service": { "type": "string" }, "version": { "type": "string" }, "contract_version": { "type": "string" }, "trust_model_version": { "const": "v3" }, "business_review_access": { "type": "object", "additionalProperties": false, "required": [ "status", "enabled", "authority_version", "rls_authority_ready" ], "properties": { "status": { "enum": [ "disabled", "blocked", "ready" ] }, "enabled": { "type": "boolean" }, "authority_version": { "const": "20260828220000" }, "rls_authority_ready": { "type": "boolean" } } }, "external_agent_webhooks_enabled": { "type": "boolean" }, "external_agent_webhooks": { "type": "object", "additionalProperties": false, "required": [ "status", "enabled", "worker_ready", "registration_available", "delivery_mode", "requirements", "missing_requirements" ], "properties": { "status": { "enum": [ "disabled", "misconfigured", "ready" ] }, "enabled": { "type": "boolean" }, "worker_ready": { "type": "boolean" }, "registration_available": { "type": "boolean" }, "delivery_mode": { "const": "signed_reference_only" }, "requirements": { "type": "object", "additionalProperties": false, "required": [ "trust_model_v3", "explicit_enablement", "release_approved", "dedicated_signing_authority", "durable_outbox_authority" ], "properties": { "trust_model_v3": { "type": "boolean" }, "explicit_enablement": { "type": "boolean" }, "release_approved": { "type": "boolean" }, "dedicated_signing_authority": { "type": "boolean" }, "durable_outbox_authority": { "type": "boolean" } } }, "missing_requirements": { "type": "array", "items": { "type": "string" } } } }, "location_handoff": { "type": "object", "additionalProperties": false, "required": [ "status", "agent_receives_coordinates" ], "properties": { "status": { "enum": [ "enabled", "disabled" ] }, "agent_receives_coordinates": { "const": false } } }, "location_choices": { "type": "object", "additionalProperties": false, "required": [ "status", "anonymous_browser_proofs_enabled", "saved_locations_enabled", "coordinates_returned" ], "properties": { "status": { "enum": [ "enabled", "disabled" ] }, "anonymous_browser_proofs_enabled": { "type": "boolean" }, "saved_locations_enabled": { "type": "boolean" }, "coordinates_returned": { "const": false } } }, "ios_app_attest_anonymous_location": { "type": "object", "additionalProperties": false, "required": [ "status", "platform", "proof", "coordinates_returned", "legacy_extension_compatibility", "unsupported_fallback" ], "properties": { "status": { "enum": [ "enabled", "disabled" ] }, "platform": { "const": "ios" }, "proof": { "const": "opaque_short_lived" }, "coordinates_returned": { "const": false }, "legacy_extension_compatibility": { "enum": [ "enabled", "disabled" ] }, "unsupported_fallback": { "const": "city_or_zip" } } }, "agent_phone_location_bridge": { "type": "object", "additionalProperties": false, "required": [ "status", "completion_mode", "push_delivery", "agent_receives_coordinates" ], "properties": { "status": { "enum": [ "enabled", "disabled" ] }, "completion_mode": { "const": "customer_device_to_existing_handoff" }, "push_delivery": { "const": "best_effort_with_in_app_recovery" }, "agent_receives_coordinates": { "const": false } } }, "mobile_push": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "registration_supported", "delivery_enabled", "provider", "reason" ], "properties": { "status": { "const": "disabled" }, "registration_supported": { "const": true }, "delivery_enabled": { "const": false }, "provider": { "const": "expo" }, "reason": { "const": "server_disabled" } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "registration_supported", "delivery_enabled", "provider", "reason" ], "properties": { "status": { "const": "ready" }, "registration_supported": { "const": true }, "delivery_enabled": { "const": true }, "provider": { "const": "expo" }, "reason": { "const": "ready" } } } ] }, "sponsored_ordering": { "type": "object", "additionalProperties": false, "required": [ "status", "model", "commercial_influence", "free_exposure_floor", "requires_precise_location_authority", "coarse_context_commercial_influence" ], "properties": { "status": { "enum": [ "enabled", "disabled" ] }, "model": { "enum": [ "sponsored_share_of_voice", "neutral" ] }, "commercial_influence": { "enum": [ "sponsored_reach_within_verification_class_and_reputation_band", "sponsored_share_of_voice", "none" ] }, "free_exposure_floor": { "type": [ "number", "null" ], "exclusiveMinimum": 0, "exclusiveMaximum": 1 }, "requires_precise_location_authority": { "const": true }, "coarse_context_commercial_influence": { "const": "none" } } }, "build_sha": { "type": "string" } } }, "OpenApiDocument": { "type": "object", "required": [ "openapi", "info", "servers", "tags", "paths", "components" ], "additionalProperties": true, "properties": { "openapi": { "const": "3.1.0" }, "info": { "type": "object", "required": [ "title", "version", "summary", "description" ], "additionalProperties": true, "properties": { "title": { "type": "string" }, "version": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": "string" } } }, "servers": { "type": "array", "items": { "type": "object", "required": [ "url" ], "additionalProperties": true, "properties": { "url": { "type": "string" }, "description": { "type": "string" } } } }, "tags": { "type": "array", "items": { "type": "object", "required": [ "name" ], "additionalProperties": true, "properties": { "name": { "type": "string" } } } }, "paths": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "object" } }, "components": { "type": "object", "required": [ "securitySchemes", "schemas" ], "additionalProperties": true, "properties": { "securitySchemes": { "type": "object", "additionalProperties": { "type": "object" } }, "schemas": { "type": "object", "additionalProperties": { "type": "object" } } } } } }, "AgentCapabilities": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Loppee v3 agent capabilities", "type": "object", "additionalProperties": true, "required": [ "schema_version", "trust_model_version", "registry_name", "external_agent_access", "external_agent_webhooks", "discovery", "agent_rules", "local_discovery_location_policy" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "registry_name": { "const": "Loppee" }, "external_agent_access": { "type": "object" }, "external_agent_webhooks": { "type": "object" }, "discovery": { "type": "object" }, "agent_rules": { "type": "object" }, "local_discovery_location_policy": { "type": "object" }, "location_choices": { "type": "object" }, "agent_phone_location_bridge": { "type": "object" } } }, "AgentSchemaCatalog": { "type": "object", "required": [ "agent_policy", "agent_capabilities", "trust_card", "search_response" ], "additionalProperties": false, "properties": { "agent_policy": { "type": "string" }, "agent_capabilities": { "type": "string" }, "trust_card": { "type": "string" }, "search_response": { "type": "string" } } }, "AgentPolicy": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Loppee v3 agent policy", "type": "object", "additionalProperties": true, "required": [ "schema_version", "trust_model_version", "external_agent_access", "external_agent_webhooks", "verification", "publication", "payment", "local_discovery_location_policy" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "external_agent_access": { "type": "object" }, "external_agent_webhooks": { "type": "object" }, "verification": { "type": "object" }, "publication": { "type": "object" }, "payment": { "type": "object" }, "local_discovery_location_policy": { "type": "object" }, "location_handoff_flow": { "type": "object" } } }, "AgentIntegration": { "type": "object", "required": [ "schema_version", "registry_name", "external_agent_access", "generated_at", "public_base_url", "package_url", "openapi_url", "openapi_v1_url", "monitoring_url", "developer_docs_url", "mcp_client_example_url", "legal", "trust_doctrine", "exposure_tiers", "mcp", "auth_model", "owner_agent_notifications", "http_api", "trust_card_contract", "commercial_influence", "rate_limits", "operational_rules" ], "additionalProperties": false, "properties": { "schema_version": { "type": "string" }, "registry_name": { "const": "Loppee" }, "external_agent_access": { "type": "object" }, "generated_at": { "type": "string", "format": "date-time" }, "public_base_url": { "type": "string" }, "package_url": { "type": "string" }, "openapi_url": { "type": "string" }, "openapi_v1_url": { "type": "string" }, "monitoring_url": { "type": "string" }, "developer_docs_url": { "type": "string" }, "mcp_client_example_url": { "type": "string" }, "legal": { "type": "object", "required": [ "privacy_policy_url", "terms_of_service_url" ], "additionalProperties": false, "properties": { "privacy_policy_url": { "type": "string" }, "terms_of_service_url": { "type": "string" } } }, "trust_doctrine": { "type": "object", "required": [ "payment", "reviews", "sponsored_placement" ], "additionalProperties": false, "properties": { "payment": { "type": "string" }, "reviews": { "type": "string" }, "sponsored_placement": { "type": "string" } } }, "exposure_tiers": { "type": "object", "additionalProperties": true }, "mcp": { "type": "object", "additionalProperties": true }, "auth_model": { "type": "object", "additionalProperties": { "type": "string" } }, "owner_agent_notifications": { "type": "object", "additionalProperties": true }, "http_api": { "type": "object", "additionalProperties": true }, "trust_card_contract": { "type": "object", "additionalProperties": true }, "commercial_influence": { "type": "object", "additionalProperties": { "type": "string" } }, "rate_limits": { "$ref": "#/components/schemas/RateLimitPolicy" }, "operational_rules": { "type": "array", "items": { "type": "string" } } } }, "RateLimitPolicy": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "object", "required": [ "window_seconds", "max_requests", "applies_to" ], "additionalProperties": false, "properties": { "window_seconds": { "type": "number" }, "max_requests": { "type": "number" }, "applies_to": { "type": "array", "items": { "type": "string" } } } } }, "AgentMonitoring": { "type": "object", "required": [ "schema_version", "registry_name", "generated_at", "service", "version", "contract_version", "build_sha", "uptime_seconds", "health_url", "integration_package_url", "openapi_url", "mcp_url", "rate_limits", "metrics" ], "additionalProperties": false, "properties": { "schema_version": { "type": "string" }, "registry_name": { "const": "Loppee" }, "generated_at": { "type": "string", "format": "date-time" }, "service": { "type": "string" }, "version": { "type": "string" }, "contract_version": { "type": "string" }, "build_sha": { "type": "string" }, "uptime_seconds": { "type": "number", "minimum": 0 }, "health_url": { "type": "string" }, "integration_package_url": { "type": "string" }, "openapi_url": { "type": "string" }, "mcp_url": { "type": "string" }, "rate_limits": { "$ref": "#/components/schemas/RateLimitPolicy" }, "metrics": { "type": "object", "required": [ "total_requests", "rate_limited_requests", "errors_4xx", "errors_5xx" ], "additionalProperties": false, "properties": { "total_requests": { "type": "number", "minimum": 0 }, "rate_limited_requests": { "type": "number", "minimum": 0 }, "errors_4xx": { "type": "number", "minimum": 0 }, "errors_5xx": { "type": "number", "minimum": 0 } } } } }, "RepositoryStatus": { "type": "object", "required": [ "source", "supabase_configured", "supabase_key_source", "public_base_url", "jobs_enabled", "writes_configured", "write_security" ], "additionalProperties": false, "properties": { "source": { "enum": [ "supabase", "static_empty" ] }, "supabase_configured": { "type": "boolean" }, "supabase_key_source": { "type": "string" }, "public_base_url": { "type": "string" }, "jobs_enabled": { "type": "boolean" }, "writes_configured": { "type": "boolean" }, "write_security": { "type": "object", "required": [ "mode", "scoped_key_count", "env_scoped_key_count", "database_scoped_key_count", "unscoped_key_allowed" ], "additionalProperties": false, "properties": { "mode": { "enum": [ "scoped_agent_keys", "legacy_unscoped", "disabled" ] }, "scoped_key_count": { "type": "number", "minimum": 0 }, "env_scoped_key_count": { "type": "number", "minimum": 0 }, "database_scoped_key_count": { "type": "number", "minimum": 0 }, "unscoped_key_allowed": { "type": "boolean" } } } } }, "BusinessIndex": { "type": "object", "additionalProperties": false, "dependentRequired": { "page_limit": [ "next_cursor" ], "next_cursor": [ "page_limit" ] }, "required": [ "schema_version", "trust_model_version", "registry_name", "generated_at", "total_registry_records", "registry_count_basis", "registry_count_observed_at", "published_profile_count", "public_base_url", "search_url", "recommend_url", "trust_card_pattern", "domain_lookup_pattern", "publishing_rule", "businesses" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "registry_name": { "const": "Loppee" }, "generated_at": { "type": "string", "format": "date-time" }, "total_registry_records": { "type": "integer", "minimum": 0 }, "registry_count_basis": { "type": "string" }, "registry_count_observed_at": { "type": [ "string", "null" ] }, "published_profile_count": { "type": "integer", "minimum": 0 }, "page_limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "next_cursor": { "type": "string", "minLength": 1 }, "public_base_url": { "type": "string" }, "search_url": { "type": "string" }, "recommend_url": { "type": "string" }, "trust_card_pattern": { "type": "string" }, "domain_lookup_pattern": { "type": "string" }, "publishing_rule": { "type": "string" }, "businesses": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] } } } } } }, "BusinessIndexEntry": { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] } } }, "PublicContentResponse": { "type": "object", "required": [ "generated_at", "source", "blocks", "trust_model_version" ], "additionalProperties": false, "properties": { "generated_at": { "type": "string", "format": "date-time" }, "source": { "enum": [ "cms", "fallback" ] }, "blocks": { "type": "object", "additionalProperties": { "type": "object", "required": [ "type", "fields", "version", "published_at" ], "additionalProperties": false, "properties": { "type": { "enum": [ "hero", "section", "card_list", "video", "banner", "text", "image", "faq" ] }, "fields": { "type": "object", "additionalProperties": true }, "version": { "type": "integer", "minimum": 1 }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "trust_model_version": { "const": "v3" } } }, "PricingResponse": { "type": "object", "required": [ "generated_at", "source", "revision_id", "published_at", "currency", "billing", "plans", "branch_add_ons", "radius_extension", "promotions", "neutrality", "trust_model_version" ], "additionalProperties": false, "properties": { "generated_at": { "type": "string", "format": "date-time" }, "source": { "enum": [ "published", "default" ] }, "revision_id": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "currency": { "const": "USD" }, "billing": { "type": "object", "required": [ "periods", "annual_paid_months", "annual_rule" ], "additionalProperties": false, "properties": { "periods": { "type": "array", "items": { "enum": [ "monthly", "annual" ] } }, "annual_paid_months": { "type": "number" }, "annual_rule": { "type": "string" } } }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PricingPlan" } }, "branch_add_ons": { "type": "array", "items": { "$ref": "#/components/schemas/PricingBranchAddOn" } }, "radius_extension": { "type": "object", "required": [ "beyond_miles", "max_miles", "per_mile_monthly_usd" ], "additionalProperties": false, "properties": { "beyond_miles": { "type": "number" }, "max_miles": { "type": "number" }, "per_mile_monthly_usd": { "type": "number" } } }, "promotions": { "type": "array", "items": { "$ref": "#/components/schemas/PricingPromotion" } }, "neutrality": { "type": "string" }, "trust_model_version": { "const": "v3" } } }, "PricingPlan": { "type": "object", "required": [ "key", "name", "tagline", "reach_label", "monthly_usd", "annual_usd", "features", "badge", "unlocks_deals", "promo" ], "additionalProperties": false, "properties": { "key": { "enum": [ "free", "nearby", "local", "regional", "metro" ] }, "name": { "type": "string" }, "tagline": { "type": "string" }, "reach_label": { "type": "string" }, "monthly_usd": { "type": "number", "minimum": 0 }, "annual_usd": { "type": "number", "minimum": 0 }, "features": { "type": "array", "items": { "type": "string" } }, "badge": { "type": "string" }, "unlocks_deals": { "type": "boolean" }, "promo": { "anyOf": [ { "$ref": "#/components/schemas/PricingPlanPromotion" }, { "type": "null" } ] } } }, "PricingPlanPromotion": { "type": "object", "required": [ "id", "label", "banner_text", "coupon_code", "applies_to_period", "ends_at", "promo_monthly_usd", "promo_annual_usd" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "banner_text": { "type": "string" }, "coupon_code": { "type": [ "string", "null" ] }, "applies_to_period": { "enum": [ "all", "monthly", "annual" ] }, "ends_at": { "type": [ "string", "null" ] }, "promo_monthly_usd": { "type": "number" }, "promo_annual_usd": { "type": "number" } } }, "PricingBranchAddOn": { "type": "object", "required": [ "radius_max_miles", "monthly_usd", "annual_usd" ], "additionalProperties": false, "properties": { "radius_max_miles": { "type": "number" }, "monthly_usd": { "type": "number" }, "annual_usd": { "type": "number" } } }, "PricingPromotion": { "type": "object", "required": [ "id", "label", "banner_text", "discount_type", "percent_off", "amount_off_usd", "coupon_code", "applies_to_period", "applies_to_tiers", "starts_at", "ends_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "banner_text": { "type": "string" }, "discount_type": { "enum": [ "percent", "fixed" ] }, "percent_off": { "type": [ "number", "null" ] }, "amount_off_usd": { "type": [ "number", "null" ] }, "coupon_code": { "type": [ "string", "null" ] }, "applies_to_period": { "enum": [ "all", "monthly", "annual" ] }, "applies_to_tiers": { "type": "array", "items": { "type": "string" } }, "starts_at": { "type": [ "string", "null" ] }, "ends_at": { "type": [ "string", "null" ] } } }, "SavedLocationRequest": { "type": "object", "additionalProperties": false, "properties": { "location_proof_id": { "type": "string", "format": "uuid" }, "zip": { "type": "string", "pattern": "^[0-9]{5}(?:-[0-9]{4})?$" }, "label": { "type": "string", "maxLength": 80 } }, "oneOf": [ { "required": [ "location_proof_id" ], "not": { "required": [ "zip" ] } }, { "required": [ "zip" ], "not": { "required": [ "location_proof_id" ] } } ] }, "SavedLocationResponse": { "type": "object", "additionalProperties": false, "required": [ "available", "saved_location_ref", "label", "kind", "reach_precision", "updated_at", "coordinates_returned" ], "properties": { "available": { "type": "boolean" }, "saved_location_ref": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "kind": { "enum": [ "saved_exact", "coarse_zip", "legacy_unverified", null ], "description": "Only saved_exact is precise local-discovery authority. coarse_zip and legacy_unverified are neutral area context only." }, "reach_precision": { "enum": [ "exact", "coarse", "none" ], "description": "Exact can authorize local category/recommendation reach; coarse cannot activate local results, Sponsored placement, or impressions." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "coordinates_returned": { "const": false } } }, "NameSuggestion": { "type": "object", "required": [ "business_id", "query", "display_name", "city", "state", "source_type" ], "additionalProperties": false, "properties": { "business_id": { "type": "null" }, "query": { "type": "string", "description": "Exact business-name query to submit to /v1/search; never a branch or profile identifier." }, "display_name": { "type": "string" }, "city": { "const": "" }, "state": { "const": "" }, "source_type": { "const": "name_query" } } }, "TaxonomySuggestion": { "type": "object", "required": [ "alias", "title", "path_titles" ], "additionalProperties": false, "properties": { "alias": { "type": "string" }, "title": { "type": "string" }, "path_titles": { "type": "array", "items": { "type": "string" } } } }, "SuggestResponse": { "type": "object", "required": [ "schema_version", "query", "names", "categories" ], "additionalProperties": false, "properties": { "schema_version": { "const": "0.1" }, "query": { "type": "string" }, "names": { "type": "array", "items": { "$ref": "#/components/schemas/NameSuggestion" }, "maxItems": 8 }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomySuggestion" }, "maxItems": 5 } } }, "GeoContextResponse": { "oneOf": [ { "type": "object", "required": [ "available", "source", "resolver", "approx", "city", "state", "latitude", "longitude" ], "additionalProperties": false, "properties": { "available": { "const": true }, "source": { "const": "ip" }, "resolver": { "enum": [ "ipinfo", "local_dataset" ] }, "approx": { "const": true }, "city": { "type": "string" }, "state": { "type": "string", "pattern": "^[A-Z]{2}$" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } } }, { "type": "object", "required": [ "available", "source", "approx" ], "additionalProperties": false, "properties": { "available": { "const": false }, "source": { "const": "ip" }, "approx": { "const": true } } } ] }, "CustomerAccountUpsertRequest": { "type": "object", "additionalProperties": false, "properties": { "full_name": { "type": "string" }, "phone": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "search_category": { "type": "string" }, "service_need": { "type": "string" }, "auth_provider": { "type": "string" }, "avatar_url": { "type": "string", "maxLength": 420000, "description": "Empty string removes the photo. Otherwise, a client-cropped square PNG/JPEG/WebP/GIF base64 data URI; decoded bytes must be at most 300 KB and dimensions at most 512×512. Raw object-storage locators and remote URLs are rejected." } } }, "CustomerAccount": { "type": "object", "required": [ "id", "full_name", "email", "phone", "city", "state", "avatar_url", "status", "created_at", "updated_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ], "format": "uri", "description": "Short-lived signed display URL for a private avatar object, or null. The internal storage locator is never returned." }, "status": { "const": "active" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CustomerAccountUpsertResponse": { "type": "object", "required": [ "status", "account" ], "additionalProperties": false, "properties": { "status": { "const": "active" }, "account": { "$ref": "#/components/schemas/CustomerAccount" } } }, "TaxonomySuggestionsResponse": { "type": "object", "required": [ "schema_version", "query", "normalized_query", "corrected_query", "count", "max_picks", "suggestions" ], "additionalProperties": false, "properties": { "schema_version": { "type": "string" }, "query": { "type": "string" }, "normalized_query": { "type": "string" }, "corrected_query": { "type": [ "string", "null" ] }, "count": { "type": "number", "minimum": 0 }, "max_picks": { "type": "number", "minimum": 1 }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomySuggestion" } } } }, "JobsSearchResponse": { "type": "object", "required": [ "schema_version", "registry_name", "feature_enabled", "generated_at", "commercial_influence", "policy", "results", "trust_model_version" ], "additionalProperties": false, "properties": { "schema_version": { "type": "string" }, "registry_name": { "type": "string" }, "feature_enabled": { "type": "boolean" }, "generated_at": { "type": "string", "format": "date-time" }, "commercial_influence": { "const": "none" }, "policy": { "type": "string" }, "query": { "type": "object", "additionalProperties": true }, "location_context": { "$ref": "#/components/schemas/LocationContext" }, "count": { "type": "number", "minimum": 0 }, "total": { "type": "number", "minimum": 0 }, "offset": { "type": "number", "minimum": 0 }, "has_more": { "type": "boolean" }, "pricing": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/JobPosting" } }, "trust_model_version": { "const": "v3" } } }, "JobPosting": { "type": "object", "additionalProperties": true, "required": [ "job_id", "business_id", "title", "description", "employer", "schema_org" ], "properties": { "job_id": { "type": "string" }, "business_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string", "description": "Maps to schema.org occupationalCategory." }, "employment_type": { "enum": [ "full_time", "part_time", "contract", "temporary", "internship", "seasonal" ] }, "workplace_type": { "enum": [ "on_site", "hybrid", "remote" ] }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "compensation_text": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" }, "maxItems": 10 }, "experience_level": { "type": "string" }, "salary_min": { "type": [ "number", "null" ] }, "salary_max": { "type": [ "number", "null" ] }, "salary_currency": { "type": "string" }, "salary_period": { "enum": [ "", "hourly", "monthly", "yearly" ] }, "benefits": { "type": "string" }, "schedule": { "type": "string" }, "applicant_location_requirements": { "type": "string" }, "total_job_openings": { "type": [ "number", "null" ] }, "direct_apply": { "type": "boolean", "description": "True when seeker/agent apply is available on-platform." }, "apply_url": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "employer": { "type": "object", "additionalProperties": true }, "schema_org": { "type": "object", "description": "Schema.org JobPosting representation returned only to an authenticated personal customer or consumer agent." }, "ranking_reason": { "type": "string" } } }, "JobApplicationRequest": { "type": "object", "required": [ "resume" ], "additionalProperties": false, "properties": { "cover_note": { "type": "string", "maxLength": 4000 }, "resume": { "$ref": "#/components/schemas/JobResumeUpload" } } }, "AgentJobApplicationRequest": { "type": "object", "required": [ "account_id", "job_id", "resume" ], "additionalProperties": false, "properties": { "account_id": { "type": "string" }, "job_id": { "type": "string" }, "cover_note": { "type": "string", "maxLength": 4000 }, "resume": { "$ref": "#/components/schemas/JobResumeUpload" } } }, "JobResumeUpload": { "type": "object", "required": [ "file_name", "content_type", "size_bytes", "data_base64" ], "additionalProperties": false, "properties": { "file_name": { "type": "string" }, "content_type": { "enum": [ "application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ] }, "size_bytes": { "type": "number", "minimum": 1, "maximum": 5242880 }, "data_base64": { "type": "string" } } }, "JobApplicationStatusRequest": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "enum": [ "viewed", "shortlisted", "rejected", "hired" ] } } }, "JobApplicationResponse": { "type": "object", "required": [ "status", "application" ], "additionalProperties": false, "properties": { "status": { "type": "string" }, "application": { "$ref": "#/components/schemas/JobApplication" }, "free_to_apply": { "type": "boolean" }, "billing": { "type": "object", "required": [ "seeker_charge_cents", "stripe_checkout_created" ], "additionalProperties": false, "properties": { "seeker_charge_cents": { "const": 0 }, "stripe_checkout_created": { "const": false } } }, "retention_note": { "type": "string" }, "already_withdrawn": { "type": "boolean" } } }, "JobApplication": { "type": "object", "required": [ "id", "job_id", "applicant_account_id", "applicant_name", "applicant_email", "cover_note", "submitted_via", "status", "resume", "job", "employer", "created_at", "updated_at", "viewed_at", "withdrawn_at", "status_updated_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "job_id": { "type": "string" }, "applicant_account_id": { "type": "string" }, "applicant_name": { "type": "string" }, "applicant_email": { "type": "string" }, "cover_note": { "type": "string" }, "submitted_via": { "enum": [ "human", "agent" ] }, "status": { "enum": [ "submitted", "viewed", "shortlisted", "rejected", "hired", "withdrawn" ] }, "resume": { "type": "object", "required": [ "file_name", "content_type", "size_bytes", "has_resume", "scan_status", "latest_scan_status", "retry_required", "replacement_pending", "replacement_retry_available", "quarantine_notice" ], "additionalProperties": false, "properties": { "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number", "minimum": 0 }, "has_resume": { "type": "boolean" }, "scan_status": { "enum": [ "unscanned", "pending", "clean", "infected", "error", "expired", "removed" ] }, "latest_scan_status": { "enum": [ "unscanned", "pending", "clean", "infected", "error", "expired", "removed" ] }, "retry_required": { "type": "boolean" }, "replacement_pending": { "type": "boolean" }, "replacement_retry_available": { "type": "boolean" }, "quarantine_notice": { "type": [ "string", "null" ] } } }, "job": { "anyOf": [ { "type": "object", "required": [ "id", "title", "status", "city", "state", "business_id" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "business_id": { "type": "string" } } }, { "type": "null" } ] }, "employer": { "anyOf": [ { "type": "object", "required": [ "business_id", "display_name", "category", "city", "state" ], "additionalProperties": false, "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" } } }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "viewed_at": { "type": [ "string", "null" ] }, "withdrawn_at": { "type": [ "string", "null" ] }, "status_updated_at": { "type": [ "string", "null" ] }, "resume_url": { "type": [ "string", "null" ] }, "resume_url_expires_in_seconds": { "type": [ "number", "null" ] } } }, "ListMyJobApplicationsRequest": { "type": "object", "required": [ "account_id" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "status": { "enum": [ "submitted", "viewed", "shortlisted", "rejected", "hired", "withdrawn" ] }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "offset": { "type": "number", "minimum": 0, "maximum": 10000 } } }, "WithdrawJobApplicationRequest": { "type": "object", "required": [ "account_id", "application_id" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "application_id": { "type": "string", "minLength": 1 } } }, "JobApplicationSummary": { "type": "object", "required": [ "id", "job_id", "applicant_name", "submitted_via", "status", "has_resume", "resume_scan_status", "resume_latest_scan_status", "resume_replacement_pending", "resume_retry_required", "resume_replacement_retry_available", "job", "employer", "created_at", "status_updated_at" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "job_id": { "type": "string" }, "applicant_name": { "type": "string" }, "submitted_via": { "enum": [ "human", "agent" ] }, "status": { "enum": [ "submitted", "viewed", "shortlisted", "rejected", "hired", "withdrawn" ] }, "has_resume": { "type": "boolean" }, "resume_scan_status": { "enum": [ "unscanned", "pending", "clean", "infected", "error", "expired", "removed" ] }, "resume_latest_scan_status": { "enum": [ "unscanned", "pending", "clean", "infected", "error", "expired", "removed" ] }, "resume_replacement_pending": { "type": "boolean" }, "resume_retry_required": { "type": "boolean" }, "resume_replacement_retry_available": { "type": "boolean" }, "job": { "$ref": "#/components/schemas/JobApplicationJob" }, "employer": { "$ref": "#/components/schemas/JobApplicationEmployer" }, "created_at": { "type": [ "string", "null" ] }, "status_updated_at": { "type": [ "string", "null" ] } } }, "JobApplicationJob": { "anyOf": [ { "type": "object", "required": [ "id", "title", "status", "city", "state", "business_id" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "business_id": { "type": "string" } } }, { "type": "null" } ] }, "JobApplicationEmployer": { "anyOf": [ { "type": "object", "required": [ "business_id", "display_name", "category", "city", "state" ], "additionalProperties": false, "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" } } }, { "type": "null" } ] }, "WithdrawJobApplicationResponse": { "type": "object", "required": [ "status", "already_withdrawn", "application" ], "additionalProperties": false, "properties": { "status": { "const": "withdrawn" }, "already_withdrawn": { "type": "boolean" }, "application": { "$ref": "#/components/schemas/JobApplicationSummary" } } }, "JobApplicationsResponse": { "type": "object", "required": [ "status", "limit", "offset", "count", "applications" ], "additionalProperties": false, "oneOf": [ { "required": [ "account_id" ] }, { "required": [ "business_id" ] } ], "properties": { "status": { "const": "ok" }, "account_id": { "type": "string" }, "business_id": { "type": "string" }, "limit": { "type": "number", "minimum": 1 }, "offset": { "type": "number", "minimum": 0 }, "count": { "type": "number", "minimum": 0 }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/JobApplicationSummary" } }, "retention_note": { "type": "string" } } }, "JobResumeSignedUrlResponse": { "type": "object", "required": [ "status", "application_id", "resume_file_name", "content_type", "size_bytes", "signed_url", "expires_in_seconds" ], "additionalProperties": false, "properties": { "status": { "const": "ok" }, "application_id": { "type": "string" }, "resume_file_name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "number", "minimum": 0 }, "signed_url": { "type": "string" }, "expires_in_seconds": { "type": "number", "minimum": 1 } } }, "ConversationWorkflowRequest": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "status": { "enum": [ "new", "open", "waiting_business", "waiting_customer", "resolved", "closed" ] }, "priority": { "enum": [ "high", "normal", "low" ] } } }, "ChatAttachmentRequest": { "type": "object", "required": [ "file_name", "content_type", "size_bytes", "data_base64" ], "additionalProperties": false, "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 180 }, "content_type": { "enum": [ "image/jpeg", "image/png", "image/webp", "application/pdf" ] }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 10485760 }, "data_base64": { "type": "string", "minLength": 4 } } }, "ChatAttachmentResponse": { "type": "object", "required": [ "status", "attachment" ], "additionalProperties": true, "properties": { "status": { "const": "uploaded" }, "attachment": { "type": "object", "required": [ "id", "fileName", "mediaType", "byteSize" ], "additionalProperties": true, "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "mediaType": { "type": "string" }, "byteSize": { "type": "integer" } } } } }, "ChatAttachmentUrlResponse": { "type": "object", "required": [ "status", "attachment" ], "additionalProperties": false, "properties": { "status": { "const": "ready" }, "attachment": { "type": "object", "required": [ "id", "file_name", "media_type", "byte_size", "signed_url", "expires_in_seconds" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "media_type": { "type": "string" }, "byte_size": { "type": "integer" }, "signed_url": { "type": "string" }, "expires_in_seconds": { "const": 600 } } } } }, "ConversationReportRequest": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "enum": [ "spam", "harassment", "impersonation", "off_platform", "unsafe", "other" ] }, "detail": { "type": "string", "maxLength": 1000 } } }, "ConversationReportResponse": { "type": "object", "required": [ "status" ], "additionalProperties": true, "properties": { "status": { "enum": [ "reported", "already_reported" ] } } }, "ConversationCloseResponse": { "type": "object", "required": [ "status", "conversation_id", "closed_at" ], "additionalProperties": false, "properties": { "status": { "const": "closed" }, "conversation_id": { "type": "string" }, "closed_at": { "type": "string", "format": "date-time" } } }, "ConversationWorkflowResponse": { "type": "object", "required": [ "status", "conversation" ], "additionalProperties": false, "properties": { "status": { "const": "updated" }, "conversation": { "type": "object", "additionalProperties": true } } }, "SupportWorkflowRequest": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "category": { "enum": [ "verification", "billing", "profile", "agent_api", "technical", "report", "general" ] }, "priority": { "enum": [ "urgent", "high", "normal", "low" ] }, "waiting_on": { "enum": [ "support", "owner", "none" ] } } }, "SupportWorkflowResponse": { "type": "object", "required": [ "status", "conversation" ], "additionalProperties": false, "properties": { "status": { "const": "updated" }, "conversation": { "type": "object", "additionalProperties": true } } }, "SupportInternalNoteRequest": { "type": "object", "required": [ "body" ], "additionalProperties": false, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 } } }, "SupportInternalNoteResponse": { "type": "object", "required": [ "status", "note" ], "additionalProperties": false, "properties": { "status": { "const": "created" }, "note": { "type": "object", "required": [ "id", "body", "authorLabel", "createdAt" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "authorLabel": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] } } } } }, "OwnerDashboardRecord": { "type": "object", "description": "One owner-scoped dashboard record. Record fields follow the corresponding typed owner-dashboard model; this aggregate contract deliberately locks the top-level collection names while allowing additive record fields.", "additionalProperties": true }, "OwnerDashboardContactVerification": { "type": "object", "required": [ "ownerEligible", "smsAvailable", "smsDestinationHint", "emailAvailable", "emailDestinationHint" ], "additionalProperties": false, "description": "Server-derived exact-owner Contact capability. Both hints are masked; clients never infer eligibility from raw business phone, session identity, claimant data, or authority fingerprints.", "properties": { "ownerEligible": { "type": "boolean" }, "smsAvailable": { "type": "boolean" }, "smsDestinationHint": { "type": [ "string", "null" ] }, "emailAvailable": { "type": "boolean" }, "emailDestinationHint": { "type": [ "string", "null" ] } } }, "OwnerDashboardBusinessClaim": { "type": "object", "description": "One owner-scoped claim. V3 responses include contactVerification so clients select only the sole exact current secured owner claim and never infer Contact eligibility from raw profile fields.", "additionalProperties": true, "properties": { "contactVerification": { "$ref": "#/components/schemas/OwnerDashboardContactVerification" } } }, "OwnerEvidenceSubmissionSummary": { "type": "object", "description": "Minimized owner-visible manual-review status. ownerReasonCode is additive and may appear only for a rejected item when owner_rejection_reason_version=1 was requested; internal reviewer notes, identifiers, and document locators are never returned.", "required": [ "id", "businessId", "factorId", "status", "createdAt" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "factorId": { "type": "string", "enum": [ "business_identity", "category_credential" ] }, "status": { "type": "string", "enum": [ "needs_review", "approved", "rejected", "superseded" ] }, "createdAt": { "type": "string", "format": "date-time" }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownerReasonCode": { "type": "string", "enum": [ "wrong_document_type", "identifier_mismatch", "holder_mismatch", "inactive_or_expired", "official_record_not_found", "qa_synthetic_fixture", "other" ] } }, "allOf": [ { "if": { "required": [ "ownerReasonCode" ] }, "then": { "properties": { "status": { "const": "rejected" } } } } ] }, "OwnerDashboardResponse": { "type": "object", "required": [ "schema_version", "generated_at", "owner", "memberships", "businesses", "applications", "locations", "mediaAssets", "externalProfiles", "verificationChecks", "ownerEvidenceSubmissions", "publicProfiles", "auditEvents", "businessClaims", "directoryListings", "serviceInteractions", "deals", "jobs", "reviews", "managementAgents", "messageReplies", "ownerNotifications", "ownerNotificationSettings", "ownerNotificationDeliveries", "categoryRequests", "analytics" ], "additionalProperties": false, "properties": { "schema_version": { "const": "0.1" }, "generated_at": { "type": "string", "format": "date-time" }, "owner": { "type": "object", "required": [ "user_id", "email" ], "additionalProperties": false, "properties": { "user_id": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "businesses": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "mediaAssets": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "externalProfiles": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "verificationChecks": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "ownerEvidenceSubmissions": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerEvidenceSubmissionSummary" } }, "publicProfiles": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "auditEvents": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "businessClaims": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardBusinessClaim" } }, "directoryListings": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "serviceInteractions": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "deals": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "managementAgents": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "messageReplies": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "ownerNotifications": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "ownerNotificationSettings": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "ownerNotificationDeliveries": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "categoryRequests": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } }, "analytics": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerDashboardRecord" } } } }, "OwnerNotification": { "type": "object", "required": [ "id", "businessId", "eventType", "resourceKind", "resourceId", "summary", "resourceUrl", "emailStatus", "webhookStatus", "dedupeKey", "readAt", "createdAt" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "eventType": { "enum": [ "customer_message", "job_application", "request", "claim_status", "review", "agent_action", "missed_contact" ] }, "resourceKind": { "enum": [ "customer_message", "job_application", "request", "claim_status", "review", "missed_contact" ] }, "resourceId": { "type": "string" }, "summary": { "type": "string" }, "resourceUrl": { "type": "string" }, "emailStatus": { "type": "string" }, "webhookStatus": { "type": "string" }, "dedupeKey": { "type": "string" }, "readAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } } }, "OwnerNotificationsResponse": { "type": "object", "required": [ "business_id", "notifications" ], "additionalProperties": false, "properties": { "business_id": { "type": "string" }, "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerNotification" } } } }, "OwnerNotificationResponse": { "type": "object", "required": [ "status", "notification" ], "additionalProperties": false, "properties": { "status": { "const": "read" }, "notification": { "$ref": "#/components/schemas/OwnerNotification" } } }, "OwnerNotificationSettingsRequest": { "type": "object", "additionalProperties": false, "properties": { "business_id": { "type": "string" }, "email_enabled": { "type": "boolean" }, "webhook_enabled": { "type": "boolean" }, "event_types": { "type": "array", "items": { "type": "string" } } } }, "OwnerNotificationSettings": { "type": "object", "required": [ "businessId", "emailEnabled", "webhookEnabled", "eventTypeSubscriptions", "createdAt", "updatedAt" ], "additionalProperties": false, "properties": { "businessId": { "type": "string" }, "emailEnabled": { "type": "boolean" }, "webhookEnabled": { "type": "boolean" }, "eventTypeSubscriptions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "OwnerNotificationSettingsResponse": { "type": "object", "required": [ "status", "settings" ], "additionalProperties": false, "properties": { "status": { "const": "updated" }, "settings": { "$ref": "#/components/schemas/OwnerNotificationSettings" } } }, "OwnerWebhookRegistrationRequest": { "type": "object", "required": [ "url" ], "additionalProperties": false, "properties": { "business_id": { "type": "string" }, "url": { "type": "string", "pattern": "^https://" }, "event_types": { "type": "array", "items": { "type": "string" } } } }, "OwnerWebhookEndpoint": { "type": "object", "required": [ "id", "businessId", "url", "eventTypeSubscriptions", "enabled", "failureCount", "lastDeliveryAt", "createdAt", "updatedAt" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "businessId": { "type": "string" }, "url": { "type": "string" }, "eventTypeSubscriptions": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "failureCount": { "type": "number", "minimum": 0 }, "lastDeliveryAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "OwnerWebhookRegistrationResponse": { "type": "object", "required": [ "status", "endpoint", "signing_secret", "one_time_display" ], "additionalProperties": false, "properties": { "status": { "enum": [ "registered", "rotated" ] }, "endpoint": { "$ref": "#/components/schemas/OwnerWebhookEndpoint" }, "signing_secret": { "type": "string" }, "one_time_display": { "const": true } } }, "OwnerWebhookEndpointResponse": { "type": "object", "required": [ "status", "endpoint" ], "additionalProperties": false, "properties": { "status": { "const": "disabled" }, "endpoint": { "$ref": "#/components/schemas/OwnerWebhookEndpoint" } } }, "DomainTrustCardResponse": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "trust_model_version", "business_id", "domain", "verification_class", "verification_disclosure", "trust_card_url", "trust_card" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "business_id": { "type": "string" }, "domain": { "type": "string" }, "verification_class": { "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "trust_card_url": { "type": "string" }, "trust_card": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Loppee v3 Trust Card", "type": "object", "additionalProperties": false, "required": [ "schema_version", "registry_name", "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "verification_valid_until", "commercial_disclosure", "legal_name", "primary_category", "services", "service_areas", "locations", "hours", "reviews", "active_deals", "commercial", "allowed_actions", "requires_human_confirmation", "brand_assets", "citation", "schema_org", "updated_at" ], "properties": { "schema_version": { "const": "3.0" }, "registry_name": { "const": "Loppee" }, "business_id": { "type": "string" }, "display_name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "array", "items": { "type": "string" } }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating", "reviews_url" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "verification_valid_until": { "type": [ "string", "null" ] }, "commercial_disclosure": { "type": "string" }, "legal_name": { "type": "string" }, "primary_category": { "type": "string" }, "services": { "type": "array", "items": { "type": "string" } }, "service_areas": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "label", "street_address", "city", "state", "zip", "is_primary" ], "properties": { "label": { "type": "string" }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "is_primary": { "type": "boolean" }, "reach_radius_miles": { "type": "number", "minimum": 0 } } } }, "hours": { "type": [ "object", "null" ], "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "rating", "title", "body", "reviewer_name", "created_at", "verification_label", "ranking_weight", "relationship", "service_date", "authoring_mode", "agent_assisted", "owner_response", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "id": { "type": "string" }, "rating": { "type": "number", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "reviewer_name": { "type": "string" }, "relationship": { "type": "string" }, "service_date": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "owner_response": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "body", "author_label", "created_at" ], "properties": { "body": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "verification_label": { "enum": [ "Unverified", "Verified interaction" ] }, "ranking_weight": { "enum": [ 0, 1 ] }, "reviewer_verification_label": { "enum": [ "Verified reviewer", "Unverified reviewer" ] }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "enum": [ 0, 1 ] } }, "allOf": [ { "if": { "properties": { "verification_label": { "const": "Verified interaction" } }, "required": [ "verification_label" ] }, "then": { "properties": { "ranking_weight": { "const": 1 } } }, "else": { "properties": { "ranking_weight": { "const": 0 } } } }, { "if": { "properties": { "reviewer_verification_label": { "const": "Verified reviewer" } }, "required": [ "reviewer_verification_label" ] }, "then": { "properties": { "quality_ranking_weight": { "const": 1 } } }, "else": { "properties": { "quality_ranking_weight": { "const": 0 } } } } ] } }, "active_deals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "commercial": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "exposure_tier", "sponsored", "influence", "sponsored_ordering", "free_exposure_floor" ], "properties": { "status": { "type": "string" }, "exposure_tier": { "type": "string" }, "sponsored": { "const": false }, "influence": { "const": "reach_only" }, "sponsored_ordering": { "const": "disabled" }, "free_exposure_floor": { "type": "null" } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "exposure_tier", "sponsored", "influence", "sponsored_ordering", "free_exposure_floor" ], "properties": { "status": { "type": "string" }, "exposure_tier": { "type": "string" }, "sponsored": { "const": false }, "influence": { "const": "reach_and_labeled_within_band_exposure" }, "sponsored_ordering": { "const": "enabled" }, "free_exposure_floor": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } } ] }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "requires_human_confirmation": { "type": "array", "items": { "type": "string" } }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "citation": { "type": "object", "additionalProperties": true }, "schema_org": { "type": "object", "additionalProperties": true }, "updated_at": { "type": "string" } } } } }, "BusinessClaimResponse": { "type": "object", "required": [ "status", "claim_id", "claim_status", "directory_listing_id", "business_id", "display_name", "created_at" ], "additionalProperties": false, "properties": { "status": { "enum": [ "queued", "already_queued" ] }, "claim_id": { "type": "string" }, "claim_status": { "type": "string" }, "directory_listing_id": { "type": [ "string", "null" ] }, "business_id": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "created_at": { "type": "string" }, "verification": { "type": "object", "additionalProperties": true } } }, "BusinessApplicationResponse": { "type": "object", "additionalProperties": false, "required": [ "status", "business_id", "application_id", "claim_id", "existing_business", "pipeline_status", "uploaded_files", "created_at", "trust_model_version" ], "properties": { "status": { "const": "submitted" }, "business_id": { "type": "string" }, "application_id": { "type": "string" }, "claim_id": { "type": [ "string", "null" ] }, "existing_business": { "type": "boolean" }, "pipeline_status": { "type": "string" }, "uploaded_files": { "type": "number", "minimum": 0 }, "created_at": { "type": "string" }, "trust_model_version": { "const": "v3" } } }, "CommercialClickResponse": { "type": "object", "required": [ "status", "storage", "click_id", "billable", "billing_status", "ledger_status", "created_at" ], "additionalProperties": false, "properties": { "status": { "enum": [ "recorded", "recorded_fallback" ] }, "storage": { "enum": [ "commercial_click_events", "service_interactions" ] }, "click_id": { "type": "string" }, "billing_event_id": { "type": [ "string", "null" ] }, "fallback_interaction_id": { "type": "string" }, "billable": { "type": "boolean" }, "billing_status": { "type": "string" }, "ledger_status": { "type": "string" }, "migration_required": { "type": "boolean" }, "created_at": { "type": "string" } } }, "AdminAgentDashboard": { "type": "object", "required": [ "schema_version", "registry_name", "generated_at", "admin", "migration_status", "summary", "accounts", "usage_events", "billing_accounts", "billing_events" ], "additionalProperties": false, "properties": { "schema_version": { "type": "string" }, "registry_name": { "const": "Loppee" }, "generated_at": { "type": "string" }, "admin": { "type": "object", "required": [ "email", "role" ], "additionalProperties": false, "properties": { "email": { "type": "string" }, "role": { "type": "string" } } }, "migration_status": { "type": "object", "additionalProperties": { "type": "boolean" } }, "summary": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } }, "accounts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage_events": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "billing_accounts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "billing_events": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "CreateAgentApiKeyRequest": { "type": "object", "required": [ "account_id" ], "additionalProperties": true, "properties": { "account_id": { "type": "string" }, "label": { "type": "string" }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "allowed_business_ids": { "type": "array", "items": { "type": "string" } }, "monthly_quota": { "type": "number" }, "rate_limit_per_minute": { "type": "number" }, "notes": { "type": "string" } } }, "CreateAgentApiKeyResponse": { "type": "object", "required": [ "status", "created_by", "key", "raw_key", "one_time_display" ], "additionalProperties": false, "properties": { "status": { "const": "created" }, "created_by": { "type": "string" }, "key": { "type": "object", "required": [ "id", "account_id", "label", "key_prefix", "key_last_four", "allowed_actions", "allowed_business_ids", "monthly_quota", "rate_limit_per_minute", "created_at" ], "additionalProperties": false, "properties": { "id": { "type": [ "string", "null" ] }, "account_id": { "type": "string" }, "label": { "type": "string" }, "key_prefix": { "type": "string" }, "key_last_four": { "type": "string" }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "allowed_business_ids": { "type": "array", "items": { "type": "string" } }, "monthly_quota": { "type": "number" }, "rate_limit_per_minute": { "type": "number" }, "created_at": { "type": "string" } } }, "raw_key": { "type": "string" }, "one_time_display": { "const": true } } }, "RevokeAgentApiKeyResponse": { "type": "object", "required": [ "status", "revoked_by", "key_id", "account_id" ], "additionalProperties": false, "properties": { "status": { "const": "revoked" }, "revoked_by": { "type": "string" }, "key_id": { "type": "string" }, "account_id": { "type": "string" } } }, "UpdateAgentBillingAccountRequest": { "type": "object", "required": [ "account_id" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "plan": { "type": "string" }, "billing_status": { "type": "string" }, "monthly_fee_cents": { "type": "number", "minimum": 0 }, "included_actions": { "type": "number", "minimum": 0 }, "overage_cents": { "type": "number", "minimum": 0 } } }, "UpdateAgentBillingAccountResponse": { "type": "object", "required": [ "status", "updated_by", "billing_account" ], "additionalProperties": false, "properties": { "status": { "const": "updated" }, "updated_by": { "type": "string" }, "billing_account": { "type": "object", "additionalProperties": true } } }, "EmptyRequest": { "type": "object", "maxProperties": 0, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "additionalProperties": false } }, "additionalProperties": false }, "RateLimitError": { "type": "object", "properties": { "error": { "const": "rate_limited" }, "message": { "type": "string" }, "retry_after_seconds": { "type": "number" } }, "required": [ "error", "message", "retry_after_seconds" ], "additionalProperties": true }, "SearchResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Loppee v3 search response", "type": "object", "additionalProperties": false, "required": [ "schema_version", "trust_model_version", "registry_name", "generated_at", "total_registry_records", "registry_count_basis", "registry_count_observed_at", "visible_candidate_records", "total_matches", "total_matches_basis", "candidate_window_truncated", "has_more", "returned_count", "search_intent", "location_context", "query", "policy", "commercial_influence", "ranking_policy", "page_limit", "next_cursor", "results" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "registry_name": { "const": "Loppee" }, "generated_at": { "type": "string", "format": "date-time" }, "total_registry_records": { "type": "integer", "minimum": 0 }, "registry_count_basis": { "type": "string" }, "registry_count_observed_at": { "type": [ "string", "null" ] }, "visible_candidate_records": { "type": "integer", "minimum": 0 }, "total_matches": { "type": "integer", "minimum": 0 }, "total_matches_basis": { "const": "bounded_candidate_window" }, "candidate_window_truncated": { "type": "boolean", "description": "True when Loppee's bounded candidate assembly reached its safety cap. total_matches is then a lower bound, never a corpus-wide exact count." }, "has_more": { "type": "boolean", "description": "True only when next_cursor can continue through the current bounded, deterministic candidate window." }, "returned_count": { "type": "integer", "minimum": 0 }, "search_intent": { "type": "object", "additionalProperties": true }, "location_context": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "source", "approx", "confidence", "free_reach_miles" ], "properties": { "source": { "enum": [ "none", "explicit", "saved_location", "saved_exact", "ip_approx", "location_handoff", "customer_location_proof", "browser_location_proof", "ios_app_attest_location_proof" ] }, "approx": { "type": "boolean" }, "confidence": { "enum": [ "precise", "coarse", "none" ] }, "free_reach_miles": { "type": "number", "minimum": 0 }, "radius_miles": { "type": [ "number", "null" ], "minimum": 0 }, "reach_policy": { "const": "per_business_plan" }, "zip": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "note": { "type": "string" }, "precise_location_required": { "type": "boolean" }, "next_action": { "enum": [ "create_location_handoff", "create_customer_location_proof", "create_browser_location_proof", "choose_location", "sign_in_for_precise_location", "continue_without_precise_location" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "source", "approx", "confidence", "free_reach_miles", "attribution" ], "properties": { "source": { "enum": [ "destination_location_handoff", "destination_location_proof" ] }, "approx": { "const": false }, "confidence": { "const": "precise" }, "free_reach_miles": { "type": "number", "minimum": 0 }, "radius_miles": { "type": [ "number", "null" ], "minimum": 0 }, "reach_policy": { "const": "per_business_plan" }, "attribution": { "const": "Google Maps", "description": "Display this exact untranslated provider attribution whenever destination-derived results or rounded distances are presented." } } } ], "description": "Local category discovery and recommendations require a current precise location proof or handoff, a user-confirmed validated destination authority, or a saved_exact Home location. City/state, ZIP, and saved_coarse locations are neutral area context for business-name disambiguation only: they return no local category or recommendation results, cannot activate Sponsored placement, and record no impressions. A connected assistant's current location comes only from the registered Loppee iPhone; provider IP, caller-supplied coordinates, host metadata, and computer/browser location are rejected as current-location authority. Exact and genuine-prefix business-name lookup remains universal; without precise location it is commercially neutral." }, "query": { "type": "object", "additionalProperties": true }, "policy": { "type": "string" }, "commercial_influence": { "type": "string", "description": "Must be none whenever current-location or saved_exact authority is absent, including universal exact/genuine-prefix name lookup." }, "ranking_policy": { "type": "string" }, "page_limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "next_cursor": { "type": [ "string", "null" ] }, "suggestions": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } } ] } } }, "allOf": [ { "if": { "properties": { "search_intent": { "type": "object", "properties": { "resolved": { "const": "name" } }, "required": [ "resolved" ] } }, "required": [ "search_intent" ] }, "then": { "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } } ] } } } }, "else": { "properties": { "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } } ] } } } } }, { "if": { "properties": { "location_context": { "type": "object", "required": [ "source" ], "properties": { "source": { "enum": [ "destination_location_handoff", "destination_location_proof" ] } } } }, "required": [ "location_context" ] }, "then": { "properties": { "commercial_influence": { "const": "none" }, "results": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "verified": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "listed": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "reviewed_registry": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "fallback_registry": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } } } } } ] }, "SearchQuery": { "type": "object", "required": [ "q", "category", "city", "state", "zip", "lat", "lng", "radius_miles", "include_directory_listings", "include_unclaimed_listings", "paid_only", "intent", "resolved_category_aliases", "resolved_category_descendant_aliases", "limit" ], "additionalProperties": false, "properties": { "q": { "type": "string" }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": [ "string", "null" ] }, "lat": { "type": "null", "const": null, "description": "Always null in connected-agent output; Loppee never returns the customer's latitude." }, "lng": { "type": "null", "const": null, "description": "Always null in connected-agent output; Loppee never returns the customer's longitude." }, "radius_miles": { "type": [ "number", "null" ] }, "include_directory_listings": { "type": "boolean" }, "include_unclaimed_listings": { "type": "boolean" }, "paid_only": { "type": "boolean" }, "consumer_reach": { "type": "boolean" }, "reach_policy": { "enum": [ "per_business_plan" ] }, "intent": { "enum": [ "category", "name", "browse" ] }, "resolved_category_aliases": { "type": "array", "items": { "type": "string" } }, "resolved_category_descendant_aliases": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "allowed_action": { "type": "string" }, "confidence": { "type": "string" } } }, "LocationContext": { "type": "object", "required": [ "source", "approx", "confidence", "free_reach_miles" ], "additionalProperties": false, "properties": { "source": { "enum": [ "none", "explicit", "saved_location", "ip_approx", "location_handoff", "destination_location_handoff", "destination_location_proof", "customer_location_proof", "browser_location_proof", "ios_app_attest_location_proof", "saved_exact" ], "description": "Only current proof/handoff, validated-destination, and saved_exact sources are precise local-discovery authority. Validated-destination requests preserve plan-based organic reach but are Sponsored-neutral. explicit, saved_location, and ip_approx are neutral context only." }, "approx": { "type": "boolean" }, "confidence": { "enum": [ "precise", "coarse", "none" ], "description": "Disclosure only. Local category/recommendation results require recognized precise authority, not merely this value. Validated-destination authority preserves plan-based organic reach but cannot activate Sponsored ordering, labels, commercial click/recommendation attribution, or exposure accounting." }, "free_reach_miles": { "type": "number" }, "zip": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "radius_miles": { "type": [ "number", "null" ] }, "reach_policy": { "enum": [ "per_business_plan" ] }, "note": { "type": "string" }, "precise_location_required": { "type": "boolean", "description": "True when coarse or missing context cannot authorize local category/recommendation reach." }, "attribution": { "const": "Google Maps", "description": "Required exact attribution for destination-derived search and recommendation results." }, "next_action": { "enum": [ "create_location_handoff", "create_customer_location_proof", "create_browser_location_proof", "choose_location", "sign_in_for_precise_location", "continue_without_precise_location" ] } }, "description": "Local category discovery and recommendations require a current precise location proof or handoff, a user-confirmed validated destination authority, or a saved_exact Home location. City/state, ZIP, and saved_coarse locations are neutral area context for business-name disambiguation only: they return no local category or recommendation results, cannot activate Sponsored placement, and record no impressions. A connected assistant's current location comes only from the registered Loppee iPhone; provider IP, caller-supplied coordinates, host metadata, and computer/browser location are rejected as current-location authority. Exact and genuine-prefix business-name lookup remains universal; without precise location it is commercially neutral.", "allOf": [ { "if": { "properties": { "source": { "enum": [ "destination_location_handoff", "destination_location_proof" ] } }, "required": [ "source" ] }, "then": { "required": [ "attribution" ], "properties": { "attribution": { "const": "Google Maps" } } } } ] }, "SearchResult": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" } } } ] }, "OpenNowStatus": { "type": [ "object", "null" ], "description": "Live owner-set-hours status, computed in the business's own IANA timezone and honoring the current special-date override. Null until the owner sets hours. Informational only: never an input to trust, ordering, reach, sponsored placement, or eligibility.", "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "is_open": { "type": [ "boolean", "null" ] }, "label": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "closes_at": { "type": [ "string", "null" ] }, "opens_at": { "type": [ "string", "null" ] }, "override_label": { "type": [ "string", "null" ] }, "time_zone": { "type": "string" }, "local_time": { "type": "string" } } }, "BusinessHours": { "type": [ "object", "null" ], "description": "Owner-set structured operating hours in the business's local timezone. Special dates replace the weekly schedule on their date. Null until set; informational only and never an input to trust, ranking, reach, or eligibility.", "required": [ "time_zone", "weekly", "special_dates", "policy" ], "additionalProperties": false, "properties": { "time_zone": { "type": [ "string", "null" ] }, "weekly": { "type": "object", "required": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ], "additionalProperties": false, "properties": { "mon": { "type": "object", "required": [ "status", "ranges" ], "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } }, "tue": { "type": "object", "required": [ "status", "ranges" ], "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } }, "wed": { "type": "object", "required": [ "status", "ranges" ], "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } }, "thu": { "type": "object", "required": [ "status", "ranges" ], "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } }, "fri": { "type": "object", "required": [ "status", "ranges" ], "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } }, "sat": { "type": "object", "required": [ "status", "ranges" ], "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } }, "sun": { "type": "object", "required": [ "status", "ranges" ], "additionalProperties": false, "properties": { "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } } } }, "special_dates": { "type": "array", "items": { "type": "object", "required": [ "date", "label", "status", "ranges" ], "additionalProperties": false, "properties": { "date": { "type": "string" }, "label": { "type": "string" }, "status": { "enum": [ "open", "closed", "open_24", "appointment" ] }, "ranges": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": [ "open", "close" ], "additionalProperties": false, "properties": { "open": { "type": "string" }, "close": { "type": "string" } } } } } } }, "policy": { "const": "informational_display_only" } } }, "TrustCard": { "oneOf": [ { "$ref": "#/components/schemas/PublishedTrustCard" }, { "$ref": "#/components/schemas/RegistryTrustCard" } ] }, "BusinessReviewsResponse": { "oneOf": [ { "$ref": "#/components/schemas/PublishedBusinessReviewsResponse" }, { "$ref": "#/components/schemas/RegistryBusinessReviewsResponse" } ] }, "PublicReview": { "type": "object", "additionalProperties": false, "required": [ "id", "rating", "title", "body", "reviewer_name", "created_at", "verification_label", "ranking_weight", "relationship", "service_date", "authoring_mode", "agent_assisted", "owner_response", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "id": { "type": "string" }, "rating": { "type": "number", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "reviewer_name": { "type": "string" }, "relationship": { "type": "string" }, "service_date": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "owner_response": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "body", "author_label", "created_at" ], "properties": { "body": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "verification_label": { "enum": [ "Unverified", "Verified interaction" ] }, "ranking_weight": { "enum": [ 0, 1 ] }, "reviewer_verification_label": { "enum": [ "Verified reviewer", "Unverified reviewer" ] }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "enum": [ 0, 1 ] } }, "allOf": [ { "if": { "properties": { "verification_label": { "const": "Verified interaction" } }, "required": [ "verification_label" ] }, "then": { "properties": { "ranking_weight": { "const": 1 } } }, "else": { "properties": { "ranking_weight": { "const": 0 } } } }, { "if": { "properties": { "reviewer_verification_label": { "const": "Verified reviewer" } }, "required": [ "reviewer_verification_label" ] }, "then": { "properties": { "quality_ranking_weight": { "const": 1 } } }, "else": { "properties": { "quality_ranking_weight": { "const": 0 } } } } ] }, "BusinessDealsResponse": { "type": "object", "required": [ "schema_version", "business_id", "deals" ], "additionalProperties": false, "properties": { "schema_version": { "type": "string" }, "business_id": { "type": "string" }, "deals": { "type": "array", "items": { "$ref": "#/components/schemas/PublicDeal" } } } }, "PublicDeal": { "type": "object", "required": [ "id", "title", "description", "discountLabel", "promoCode", "terms", "startsAt", "endsAt", "createdAt" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "discountLabel": { "type": "string" }, "promoCode": { "type": [ "string", "null" ] }, "terms": { "type": [ "string", "null" ] }, "startsAt": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } } }, "SaveBusinessRequest": { "type": "object", "required": [ "account_id", "business_id", "business_name", "business_source" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "business_id": { "type": "string", "minLength": 1 }, "business_name": { "type": "string", "minLength": 1 }, "business_source": { "type": "string", "minLength": 1 }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "notes": { "type": "string" } } }, "SaveBusinessResponse": { "type": "object", "required": [ "status", "saved_business_id", "business_id", "account_id", "created_at" ], "additionalProperties": false, "properties": { "status": { "const": "saved" }, "saved_business_id": { "type": "string" }, "business_id": { "type": "string" }, "account_id": { "type": "string" }, "created_at": { "type": "string" } } }, "ListSavedBusinessesRequest": { "type": "object", "required": [ "account_id" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "limit": { "type": "number", "minimum": 1, "maximum": 100 } } }, "SavedBusinessesResponse": { "type": "object", "required": [ "account_id", "count", "saved_businesses" ], "additionalProperties": false, "properties": { "account_id": { "type": "string" }, "count": { "type": "number", "minimum": 0 }, "saved_businesses": { "type": "array", "items": { "type": "object", "required": [ "business_id", "business_name", "business_source", "category", "city", "state", "notes", "saved_at" ], "additionalProperties": false, "properties": { "business_id": { "type": "string" }, "business_name": { "type": "string" }, "business_source": { "type": "string" }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "notes": { "type": "string" }, "saved_at": { "type": [ "string", "null" ] } } } } } }, "UnsaveBusinessRequest": { "type": "object", "required": [ "account_id", "business_id" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "business_id": { "type": "string", "minLength": 1 } } }, "UnsaveBusinessResponse": { "type": "object", "required": [ "status", "account_id", "business_id", "removed" ], "additionalProperties": false, "properties": { "status": { "const": "unsaved" }, "account_id": { "type": "string" }, "business_id": { "type": "string" }, "removed": { "type": "boolean" } } }, "MessageRequest": { "type": "object", "required": [ "account_id", "target_business_id", "target_business_name", "target_business_source", "subject", "message", "client_message_id" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "target_business_id": { "type": "string", "minLength": 1 }, "target_business_name": { "type": "string", "minLength": 1 }, "target_business_source": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "client_message_id": { "type": "string", "minLength": 8, "maxLength": 80, "pattern": "^[A-Za-z0-9_-]{8,80}$", "description": "Caller-stable retry key. Exact replay is idempotent; reuse with different content is rejected." } } }, "PublicMessageRequest": { "type": "object", "required": [ "target_business_id", "message" ], "additionalProperties": false, "properties": { "target_business_id": { "type": "string", "minLength": 1 }, "target_business_name": { "type": "string" }, "target_business_source": { "type": "string" }, "subject": { "type": "string" }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 }, "source_path": { "type": "string" } } }, "MessageResponse": { "type": "object", "required": [ "status", "conversation_id", "interaction_id", "account_id", "target_business_id", "created_at", "client_message_id", "idempotent_replay" ], "additionalProperties": false, "properties": { "status": { "const": "message_received" }, "conversation_id": { "type": "string" }, "interaction_id": { "type": "string" }, "account_id": { "type": "string" }, "target_business_id": { "type": "string" }, "target_business_name": { "type": "string" }, "created_at": { "type": "string" }, "moderation_required": { "const": false }, "delivery": { "const": "delivered_to_business_inbox" }, "client_message_id": { "type": "string" }, "idempotent_replay": { "type": "boolean" } } }, "ListMyConversationsRequest": { "type": "object", "required": [ "account_id" ], "additionalProperties": false, "properties": { "account_id": { "type": "string", "minLength": 1 }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Exact conversation referenced by a webhook; returns zero or one scoped thread." }, "cursor": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Opaque pagination cursor returned by the previous page. Do not combine with conversation_id." }, "limit": { "type": "number", "minimum": 1, "maximum": 100 } } }, "ConversationsResponse": { "type": "object", "required": [ "account_id", "count", "pagination", "conversations" ], "additionalProperties": false, "properties": { "account_id": { "type": "string" }, "count": { "type": "number", "minimum": 0 }, "pagination": { "type": "object", "additionalProperties": false, "required": [ "limit", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "conversations": { "type": "array", "items": { "type": "object", "required": [ "conversation_id", "business_id", "business_name", "subject", "message", "status", "created_at", "replies" ], "additionalProperties": false, "properties": { "conversation_id": { "type": "string" }, "business_id": { "type": "string" }, "business_name": { "type": "string" }, "subject": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "type": "object", "required": [ "body", "author_type", "author_label", "created_at" ], "additionalProperties": false, "properties": { "body": { "type": "string" }, "author_type": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } } } } } } } } }, "ReviewRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "account_id": { "type": "string", "minLength": 1 }, "target_business_id": { "type": "string", "minLength": 1 }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "subject": { "type": "string", "minLength": 3, "maxLength": 160 }, "message": { "type": "string", "minLength": 20, "maxLength": 4000 }, "service_date": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } ], "description": "Optional real, non-future service date in YYYY-MM-DD format; empty means not provided." }, "attestation_accepted": { "type": "boolean", "const": true, "description": "Set true only after the customer confirms this describes their own experience and explicitly approves publishing the displayed business, star rating, title, and full review. Approval does not establish independently verified service evidence." }, "customer_confirmed": { "type": "boolean", "description": "Set true to confirm you were a customer of this business. Required when the target business has not claimed its page." } }, "required": [ "account_id", "target_business_id", "rating", "subject", "message", "attestation_accepted" ], "additionalProperties": false }, "PublicReviewRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "target_business_id": { "type": "string", "minLength": 1 }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "subject": { "type": "string", "minLength": 3, "maxLength": 160 }, "message": { "type": "string", "minLength": 20, "maxLength": 4000 }, "service_date": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } ], "description": "Optional real, non-future service date in YYYY-MM-DD format; empty means not provided." }, "attestation_accepted": { "type": "boolean", "const": true }, "customer_confirmed": { "type": "boolean", "description": "Set true to confirm you were a customer of this business. Required when the target business has not claimed its page." } }, "required": [ "target_business_id", "rating", "subject", "message", "attestation_accepted" ], "additionalProperties": false }, "ReviewResponse": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "trust_model_version", "review_id", "account_id", "target_business_id", "target_business_name", "rating", "visibility", "verification_label", "ranking_weight", "authoring_mode", "agent_assisted", "moderation_policy", "created_at", "target_source", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "status": { "enum": [ "review_published", "review_updated" ] }, "trust_model_version": { "const": "v3" }, "review_id": { "type": "string" }, "account_id": { "type": "string" }, "target_business_id": { "type": "string" }, "target_business_name": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "visibility": { "enum": [ "public", "removed" ] }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "moderation_policy": { "type": "string" }, "created_at": { "type": "string" }, "target_source": { "enum": [ "published_profile", "registry_record" ] }, "verification_label": { "const": "Unverified" }, "ranking_weight": { "const": 0 }, "reviewer_verification_label": { "const": "Verified reviewer" }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "const": 1 } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "trust_model_version", "review_id", "account_id", "target_business_id", "target_business_name", "rating", "visibility", "verification_label", "ranking_weight", "authoring_mode", "agent_assisted", "moderation_policy", "created_at", "target_source", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "status": { "enum": [ "review_published", "review_updated" ] }, "trust_model_version": { "const": "v3" }, "review_id": { "type": "string" }, "account_id": { "type": "string" }, "target_business_id": { "type": "string" }, "target_business_name": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "visibility": { "enum": [ "public", "removed" ] }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "moderation_policy": { "type": "string" }, "created_at": { "type": "string" }, "target_source": { "enum": [ "published_profile", "registry_record" ] }, "verification_label": { "const": "Verified interaction" }, "ranking_weight": { "const": 1 }, "reviewer_verification_label": { "const": "Verified reviewer" }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "const": 1 } } } ] }, "AgentConnectionTestRequest": { "type": "object", "additionalProperties": false, "properties": { "key": { "type": "string", "description": "Optional UI fallback. Prefer X-LOPPEE-API-Key or Authorization: Bearer; never put a key in the URL." } } }, "AgentConnectionIdentity": { "type": "object", "required": [ "account_id", "label", "allowed_actions", "allowed_business_ids", "source", "scope_kind" ], "additionalProperties": false, "properties": { "account_id": { "type": "string" }, "label": { "type": "string" }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "allowed_business_ids": { "type": "array", "items": { "type": "string" } }, "source": { "enum": [ "database", "environment", "legacy" ] }, "scope_kind": { "enum": [ "consumer", "management", "team", "operator", "unknown" ] } } }, "AgentConnectionTestResponse": { "oneOf": [ { "type": "object", "required": [ "ok", "identity" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "identity": { "$ref": "#/components/schemas/AgentConnectionIdentity" } } }, { "type": "object", "required": [ "ok", "reason" ], "additionalProperties": false, "properties": { "ok": { "const": false }, "reason": { "enum": [ "missing_key", "invalid_key" ] } } } ] }, "AgentAccessRequest": { "type": "object", "required": [ "organization_name", "agent_name", "developer_email" ], "additionalProperties": false, "properties": { "organization_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "agent_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "agent_type": { "type": "string" }, "website": { "type": "string" }, "developer_email": { "type": "string", "minLength": 1, "maxLength": 254 }, "use_case": { "type": "string" }, "target_categories": { "type": "array", "items": { "type": "string" } }, "operating_states": { "type": "array", "items": { "type": "string" } }, "requested_actions": { "type": "array", "items": { "type": "string" } }, "callback_url": { "type": "string" }, "data_needs": { "type": "string" }, "safety_contact": { "type": "string" }, "compliance_notes": { "type": "string" } } }, "AgentAccessResponse": { "type": "object", "required": [ "status", "request_id", "request_status", "created_at" ], "additionalProperties": false, "properties": { "status": { "const": "queued" }, "request_id": { "type": "string" }, "request_status": { "type": "string" }, "created_at": { "type": "string" } } }, "ClaimVerificationSendRequest": { "type": "object", "required": [ "claim_id" ], "additionalProperties": false, "properties": { "claim_id": { "type": "string", "minLength": 1 }, "channel": { "enum": [ "email", "sms" ] }, "request_id": { "type": "string", "format": "uuid", "description": "Caller-generated idempotency UUID. Required for trust model v3 SMS and owner-email sends; optional for the compatible v2 path." } } }, "ClaimVerificationSendResponse": { "type": "object", "required": [ "status", "channel" ], "additionalProperties": false, "properties": { "status": { "enum": [ "code_sent", "already_verified", "no_destination", "pending_sms_provider", "failed_sms_provider", "unknown_sms_provider", "pending_email_provider", "failed_email_provider", "unknown_email_provider" ] }, "channel": { "enum": [ "email", "sms" ] }, "provider_status": { "enum": [ "accepted", "pending", "failed", "unknown" ], "description": "V3 provider request state. accepted means only that the provider accepted the request; it does not prove inbox or handset delivery." }, "recipient_delivery_confirmed": { "const": false, "description": "V3 currently has no final-delivery provider event for this receipt. This field prevents code_sent from being interpreted as confirmed recipient delivery." }, "challenge_id": { "type": "string", "format": "uuid", "description": "Opaque v3 SMS or owner-email challenge UUID. Present when a challenge can be verified and must be returned unchanged." }, "destination_hint": { "type": "string" }, "expires_in_seconds": { "type": "number", "minimum": 1 } } }, "ClaimVerificationVerifyRequest": { "type": "object", "required": [ "claim_id", "code" ], "additionalProperties": false, "properties": { "claim_id": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1, "maxLength": 12 }, "channel": { "enum": [ "email", "sms" ] }, "challenge_id": { "type": "string", "format": "uuid", "description": "Exact challenge UUID returned by the v3 SMS or owner-email send. Required for v3 SMS verification and owner-email verification; optional for the compatible v2 path." } } }, "ClaimVerificationVerifyResponse": { "type": "object", "required": [ "status", "business_id" ], "additionalProperties": false, "properties": { "status": { "enum": [ "already_verified", "queued_for_transfer_review", "verified", "contact_verified" ] }, "method": { "enum": [ "email_code", "sms_code" ] }, "business_id": { "type": [ "string", "null" ] }, "transfer_review_required": { "const": true }, "trust_model_version": { "const": "v3" }, "publication": { "type": "object", "additionalProperties": true } } }, "ContactRecordedRequest": { "type": "object", "required": [ "business_id" ], "additionalProperties": false, "properties": { "business_id": { "type": "string", "minLength": 1 } } }, "ContactRecordedResponse": { "type": "object", "required": [ "ok", "business_id", "status", "contact_recorded", "trust_weight", "verified", "interaction_id", "review_upgraded", "policy" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "business_id": { "type": "string" }, "status": { "const": "contact_recorded" }, "contact_recorded": { "const": true }, "trust_weight": { "const": 0 }, "verified": { "const": false }, "interaction_id": { "type": "string" }, "review_upgraded": { "const": false }, "policy": { "type": "string" } } }, "PromoteVerifiedTransactionRequest": { "type": "object", "required": [ "business_id", "evidence_id" ], "additionalProperties": false, "properties": { "business_id": { "type": "string", "minLength": 1 }, "evidence_id": { "type": "string", "minLength": 1 } } }, "PromoteVerifiedTransactionResponse": { "type": "object", "required": [ "ok", "status", "business_id", "verified", "trust_weight", "interaction_id", "review_upgraded", "evidence_id" ], "additionalProperties": false, "properties": { "ok": { "const": true }, "status": { "const": "verified_transaction_promoted" }, "business_id": { "type": "string" }, "verified": { "const": true }, "trust_weight": { "const": 1 }, "interaction_id": { "type": "string" }, "review_upgraded": { "type": "boolean" }, "evidence_id": { "type": "string" } } }, "BusinessClaimRequest": { "type": "object", "required": [ "display_name" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string" }, "business_id": { "type": "string" }, "display_name": { "type": "string", "minLength": 1 }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "source_type": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string" }, "claimant_email": { "type": "string", "description": "Legacy field; authenticated owner identity wins." }, "claimant_name": { "type": "string", "description": "Legacy field; authenticated owner identity wins." }, "claimant_relationship": { "type": "string" }, "notes": { "type": "string" } } }, "BusinessApplicationRequest": { "type": "object", "required": [ "application" ], "additionalProperties": false, "properties": { "application": { "type": "object", "required": [ "legalName", "displayName", "website", "phone", "streetAddress", "city", "state", "zip", "category", "taxonomyCategoryAliases", "ownerEmail" ], "additionalProperties": false, "properties": { "legalName": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "logoFileName": { "type": "string" }, "businessPhotoFileNames": { "type": "array", "items": { "type": "string" } }, "website": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 }, "streetAddress": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 }, "zip": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "taxonomyCategoryAliases": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }, "licenseNumber": { "type": "string" }, "licenseState": { "type": "string" }, "insuranceFileName": { "type": "string" }, "insuranceStatus": { "enum": [ "not_provided", "provided" ], "description": "Insurance certificate provided by the business. Not independently confirmed by Loppee." }, "googleBusinessProfileUrl": { "type": "string" }, "facebookPageUrl": { "type": "string" }, "bbbProfileUrl": { "type": "string" }, "services": { "type": "string" }, "serviceAreas": { "type": "string" }, "categoryEvidence": { "type": "object", "additionalProperties": { "type": "string" } }, "complianceAttestations": { "type": "object", "additionalProperties": { "type": "boolean" } }, "ownerEmail": { "type": "string", "minLength": 1 }, "notes": { "type": "string" } } }, "claim_id": { "type": "string" }, "business_id": { "type": "string" }, "listing_id": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "required": [ "kind", "fileName", "contentType", "sizeBytes", "dataBase64" ], "additionalProperties": false, "properties": { "kind": { "enum": [ "logo", "business_photo", "insurance_document" ] }, "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "number", "minimum": 1 }, "dataBase64": { "type": "string", "minLength": 1 } } } } } }, "CommercialClickRequest": { "type": "object", "required": [ "action_type", "source_type" ], "additionalProperties": false, "properties": { "action_type": { "enum": [ "website", "call", "view_profile", "claim", "trust_card", "badge", "directions", "recommend" ] }, "source_type": { "enum": [ "published_profile", "directory_listing" ] }, "business_id": { "type": "string" }, "listing_id": { "type": "string" }, "directory_listing_id": { "type": "string", "description": "Deprecated alias of listing_id." }, "display_name": { "type": "string" }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "commercial_status": { "enum": [ "free", "paid", "sponsored" ] }, "target_url": { "type": "string" }, "page_path": { "type": "string" }, "referrer": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "RecommendationResponse": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Loppee v3 recommendation response", "type": "object", "additionalProperties": false, "required": [ "schema_version", "trust_model_version", "registry_name", "generated_at", "total_registry_records", "registry_count_basis", "registry_count_observed_at", "visible_candidate_records", "total_matches", "total_matches_basis", "candidate_window_truncated", "has_more", "returned_count", "search_intent", "location_context", "query", "policy", "commercial_influence", "ranking_policy", "results", "endpoint", "ordering", "verified", "listed", "reviewed_registry", "fallback_registry" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "registry_name": { "const": "Loppee" }, "generated_at": { "type": "string", "format": "date-time" }, "total_registry_records": { "type": "integer", "minimum": 0 }, "registry_count_basis": { "type": "string" }, "registry_count_observed_at": { "type": [ "string", "null" ] }, "visible_candidate_records": { "type": "integer", "minimum": 0 }, "total_matches": { "type": "integer", "minimum": 0 }, "total_matches_basis": { "const": "bounded_candidate_window" }, "candidate_window_truncated": { "type": "boolean", "description": "True when Loppee's bounded candidate assembly reached its safety cap. total_matches is then a lower bound, never a corpus-wide exact count." }, "has_more": { "type": "boolean", "description": "True only when next_cursor can continue through the current bounded, deterministic candidate window." }, "returned_count": { "type": "integer", "minimum": 0 }, "search_intent": { "type": "object", "additionalProperties": true }, "location_context": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "source", "approx", "confidence", "free_reach_miles" ], "properties": { "source": { "enum": [ "none", "explicit", "saved_location", "saved_exact", "ip_approx", "location_handoff", "customer_location_proof", "browser_location_proof", "ios_app_attest_location_proof" ] }, "approx": { "type": "boolean" }, "confidence": { "enum": [ "precise", "coarse", "none" ] }, "free_reach_miles": { "type": "number", "minimum": 0 }, "radius_miles": { "type": [ "number", "null" ], "minimum": 0 }, "reach_policy": { "const": "per_business_plan" }, "zip": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "city": { "type": "string" }, "state": { "type": "string" }, "note": { "type": "string" }, "precise_location_required": { "type": "boolean" }, "next_action": { "enum": [ "create_location_handoff", "create_customer_location_proof", "create_browser_location_proof", "choose_location", "sign_in_for_precise_location", "continue_without_precise_location" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "source", "approx", "confidence", "free_reach_miles", "attribution" ], "properties": { "source": { "enum": [ "destination_location_handoff", "destination_location_proof" ] }, "approx": { "const": false }, "confidence": { "const": "precise" }, "free_reach_miles": { "type": "number", "minimum": 0 }, "radius_miles": { "type": [ "number", "null" ], "minimum": 0 }, "reach_policy": { "const": "per_business_plan" }, "attribution": { "const": "Google Maps", "description": "Display this exact untranslated provider attribution whenever destination-derived results or rounded distances are presented." } } } ], "description": "Local category discovery and recommendations require a current precise location proof or handoff, a user-confirmed validated destination authority, or a saved_exact Home location. City/state, ZIP, and saved_coarse locations are neutral area context for business-name disambiguation only: they return no local category or recommendation results, cannot activate Sponsored placement, and record no impressions. A connected assistant's current location comes only from the registered Loppee iPhone; provider IP, caller-supplied coordinates, host metadata, and computer/browser location are rejected as current-location authority. Exact and genuine-prefix business-name lookup remains universal; without precise location it is commercially neutral." }, "query": { "type": "object", "additionalProperties": true }, "policy": { "type": "string" }, "commercial_influence": { "type": "string", "description": "Must be none whenever current-location or saved_exact authority is absent, including universal exact/genuine-prefix name lookup." }, "ranking_policy": { "type": "string" }, "suggestions": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "const": 0 }, "quality_rating": { "type": "null" } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_verification", "warning" ], "properties": { "status": { "const": "eligible_only_as_last_resort_without_verified_reviewer_rating" }, "basis": { "const": "no_published_or_identity_reviewed_registry_candidate_within_category_and_free_reach" }, "max_reach_miles": { "const": 3 }, "business_verification": { "const": "not_verified" }, "warning": { "const": "This unclaimed business has no identity-verified reviewer ratings. Loppee has not verified it; the customer should independently check the business before making contact or booking service." } } } } } ] } }, "endpoint": { "const": "recommend_businesses" }, "ordering": { "enum": [ "verified_listed_reviewed_registry_fill", "registry_last_resort_fallback", "direct_entity_relevance" ] }, "verified": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } } }, "listed": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } } }, "reviewed_registry": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } } ] } }, "fallback_registry": { "type": "array", "maxItems": 1, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "const": 0 }, "quality_rating": { "type": "null" } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_verification", "warning" ], "properties": { "status": { "const": "eligible_only_as_last_resort_without_verified_reviewer_rating" }, "basis": { "const": "no_published_or_identity_reviewed_registry_candidate_within_category_and_free_reach" }, "max_reach_miles": { "const": 3 }, "business_verification": { "const": "not_verified" }, "warning": { "const": "This unclaimed business has no identity-verified reviewer ratings. Loppee has not verified it; the customer should independently check the business before making contact or booking service." } } } } } ] } } }, "allOf": [ { "if": { "properties": { "search_intent": { "type": "object", "required": [ "resolved" ], "properties": { "resolved": { "const": "name" } } } }, "required": [ "search_intent" ] }, "then": { "properties": { "ordering": { "const": "direct_entity_relevance" }, "commercial_influence": { "const": "none" }, "verified": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } } }, "listed": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } } }, "reviewed_registry": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } } ] } }, "fallback_registry": { "maxItems": 0 }, "results": { "type": "array", "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } } ] } } } } }, { "if": { "properties": { "fallback_registry": { "minItems": 1 } }, "required": [ "fallback_registry" ] }, "then": { "properties": { "verified": { "maxItems": 0 }, "listed": { "maxItems": 0 }, "reviewed_registry": { "maxItems": 0 }, "ordering": { "const": "registry_last_resort_fallback" }, "search_intent": { "type": "object", "required": [ "resolved" ], "properties": { "resolved": { "const": "category" } } }, "query": { "type": "object", "required": [ "include_registry_recommendations" ], "properties": { "include_registry_recommendations": { "const": true } } }, "results": { "minItems": 1, "maxItems": 1, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "const": 0 }, "quality_rating": { "type": "null" } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_verification", "warning" ], "properties": { "status": { "const": "eligible_only_as_last_resort_without_verified_reviewer_rating" }, "basis": { "const": "no_published_or_identity_reviewed_registry_candidate_within_category_and_free_reach" }, "max_reach_miles": { "const": 3 }, "business_verification": { "const": "not_verified" }, "warning": { "const": "This unclaimed business has no identity-verified reviewer ratings. Loppee has not verified it; the customer should independently check the business before making contact or booking service." } } } } } ] } } } } }, { "if": { "properties": { "reviewed_registry": { "minItems": 1 } }, "required": [ "reviewed_registry" ] }, "then": { "properties": { "search_intent": { "type": "object", "required": [ "resolved" ], "properties": { "resolved": { "enum": [ "category", "name" ] } } }, "query": { "type": "object", "required": [ "include_registry_recommendations" ], "properties": { "include_registry_recommendations": { "const": true } } } } } }, { "if": { "allOf": [ { "properties": { "reviewed_registry": { "minItems": 1 } }, "required": [ "reviewed_registry" ] }, { "properties": { "search_intent": { "type": "object", "required": [ "resolved" ], "properties": { "resolved": { "const": "category" } } } }, "required": [ "search_intent" ] } ] }, "then": { "properties": { "ordering": { "const": "verified_listed_reviewed_registry_fill" }, "reviewed_registry": { "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } } ] } }, "results": { "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "reach_eligibility", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0, "maximum": 3 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reach_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "max_reach_miles", "location_authority" ], "properties": { "status": { "const": "within_free_reach" }, "max_reach_miles": { "const": 3 }, "location_authority": { "const": "precise_private" } } }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "max_reach_miles", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_within_free_reach" }, "max_reach_miles": { "const": 3 }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } } ] } } } } }, { "if": { "allOf": [ { "properties": { "reviewed_registry": { "minItems": 1 } }, "required": [ "reviewed_registry" ] }, { "properties": { "search_intent": { "type": "object", "required": [ "resolved" ], "properties": { "resolved": { "const": "name" } } } }, "required": [ "search_intent" ] } ] }, "then": { "properties": { "ordering": { "const": "direct_entity_relevance" }, "fallback_registry": { "maxItems": 0 }, "reviewed_registry": { "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } } ] } }, "results": { "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "source_type", "sponsored", "commercial_status", "exposure_tier", "open_now", "ranking_reason" ], "properties": { "business_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_type": { "const": "published_profile" }, "claim_status": { "const": "claimed" }, "sponsored": { "type": "boolean", "description": "True only when precise location authority permitted Sponsored placement for this request. Coarse context and location-free name lookup must emit false." }, "distance_miles": { "type": "number", "minimum": 0 }, "commercial_status": { "type": "string" }, "exposure_tier": { "type": "string" }, "open_now": { "type": [ "object", "null" ], "additionalProperties": true }, "ranking_reason": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "unclaimed_registry_record" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_verification" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_verification": { "const": "not_verified" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } }, { "type": "object", "additionalProperties": false, "required": [ "trust_model_version", "subject_kind", "disclosure", "source_type", "listing_id", "display_name", "category", "city", "state", "website", "phone", "source_name", "source_url", "sponsored", "ranking_reason", "public_profile_url", "review_reputation", "commercial_influence", "claim_status", "recommendation_eligibility" ], "properties": { "trust_model_version": { "const": "v3" }, "subject_kind": { "const": "business_registry_record" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "listing_id": { "type": "string" }, "display_name": { "type": "string" }, "street_address": { "type": [ "string", "null" ], "description": "Public Registry street address when returned by the owner Claim-candidate route; null means the source record has no exact address." }, "zip": { "type": [ "string", "null" ], "description": "Public Registry postal code when returned by the owner Claim-candidate route." }, "category": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_url": { "type": [ "string", "null" ] }, "sponsored": { "const": false }, "distance_miles": { "type": "number", "minimum": 0 }, "ranking_reason": { "type": "string" }, "public_profile_url": { "type": "string" }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 1 }, "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "commercial_influence": { "const": "none" }, "recommendation_eligibility": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "business_class", "publication_status" ], "properties": { "status": { "const": "eligible_with_verified_reviewer_review" }, "basis": { "const": "at_least_one_identity_verified_reviewer_review_for_direct_name_lookup" }, "business_class": { "const": "registry_record" }, "publication_status": { "const": "not_published_as_verified_or_listed" } } } } } ] } } } } }, { "if": { "properties": { "location_context": { "type": "object", "required": [ "source" ], "properties": { "source": { "enum": [ "destination_location_handoff", "destination_location_proof" ] } } } }, "required": [ "location_context" ] }, "then": { "properties": { "commercial_influence": { "const": "none" }, "results": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "verified": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "listed": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "reviewed_registry": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } }, "fallback_registry": { "type": "array", "items": { "type": "object", "required": [ "sponsored" ], "properties": { "sponsored": { "const": false } } } } } } } ] }, "PublishedTrustCard": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Loppee v3 Trust Card", "type": "object", "additionalProperties": false, "required": [ "schema_version", "registry_name", "business_id", "display_name", "domain", "category", "city", "state", "website", "phone", "trust_model_version", "verification_class", "verification_disclosure", "review_reputation", "trust_card_url", "public_profile_url", "verification_valid_until", "commercial_disclosure", "legal_name", "primary_category", "services", "service_areas", "locations", "hours", "reviews", "active_deals", "commercial", "allowed_actions", "requires_human_confirmation", "brand_assets", "citation", "schema_org", "updated_at" ], "properties": { "schema_version": { "const": "3.0" }, "registry_name": { "const": "Loppee" }, "business_id": { "type": "string" }, "display_name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "category": { "type": "array", "items": { "type": "string" } }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "trust_model_version": { "const": "v3" }, "verification_class": { "type": "string", "enum": [ "verified", "listed" ] }, "verification_disclosure": { "type": "string", "enum": [ "Loppee completed this business's registration, professional license, and contact checks.", "Loppee completed this business's registration and contact checks.", "Recommended by customers. NOT verified by Loppee.", "Listed on Loppee. NOT verified by Loppee." ] }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating", "reviews_url" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "verification_valid_until": { "type": [ "string", "null" ] }, "commercial_disclosure": { "type": "string" }, "legal_name": { "type": "string" }, "primary_category": { "type": "string" }, "services": { "type": "array", "items": { "type": "string" } }, "service_areas": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "label", "street_address", "city", "state", "zip", "is_primary" ], "properties": { "label": { "type": "string" }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "is_primary": { "type": "boolean" }, "reach_radius_miles": { "type": "number", "minimum": 0 } } } }, "hours": { "type": [ "object", "null" ], "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "rating", "title", "body", "reviewer_name", "created_at", "verification_label", "ranking_weight", "relationship", "service_date", "authoring_mode", "agent_assisted", "owner_response", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "id": { "type": "string" }, "rating": { "type": "number", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "reviewer_name": { "type": "string" }, "relationship": { "type": "string" }, "service_date": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "owner_response": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "body", "author_label", "created_at" ], "properties": { "body": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "verification_label": { "enum": [ "Unverified", "Verified interaction" ] }, "ranking_weight": { "enum": [ 0, 1 ] }, "reviewer_verification_label": { "enum": [ "Verified reviewer", "Unverified reviewer" ] }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "enum": [ 0, 1 ] } }, "allOf": [ { "if": { "properties": { "verification_label": { "const": "Verified interaction" } }, "required": [ "verification_label" ] }, "then": { "properties": { "ranking_weight": { "const": 1 } } }, "else": { "properties": { "ranking_weight": { "const": 0 } } } }, { "if": { "properties": { "reviewer_verification_label": { "const": "Verified reviewer" } }, "required": [ "reviewer_verification_label" ] }, "then": { "properties": { "quality_ranking_weight": { "const": 1 } } }, "else": { "properties": { "quality_ranking_weight": { "const": 0 } } } } ] } }, "active_deals": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "commercial": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "exposure_tier", "sponsored", "influence", "sponsored_ordering", "free_exposure_floor" ], "properties": { "status": { "type": "string" }, "exposure_tier": { "type": "string" }, "sponsored": { "const": false }, "influence": { "const": "reach_only" }, "sponsored_ordering": { "const": "disabled" }, "free_exposure_floor": { "type": "null" } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "exposure_tier", "sponsored", "influence", "sponsored_ordering", "free_exposure_floor" ], "properties": { "status": { "type": "string" }, "exposure_tier": { "type": "string" }, "sponsored": { "const": false }, "influence": { "const": "reach_and_labeled_within_band_exposure" }, "sponsored_ordering": { "const": "enabled" }, "free_exposure_floor": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1 } } } ] }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "requires_human_confirmation": { "type": "array", "items": { "type": "string" } }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "citation": { "type": "object", "additionalProperties": true }, "schema_org": { "type": "object", "additionalProperties": true }, "updated_at": { "type": "string" } } }, "RegistryTrustCard": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Loppee v3 Registry Trust Card", "type": "object", "additionalProperties": false, "required": [ "schema_version", "trust_model_version", "registry_name", "subject_kind", "source_type", "claim_status", "disclosure", "business_id", "display_name", "legal_name", "domain", "primary_category", "category", "services", "service_areas", "city", "state", "website", "phone", "locations", "hours", "reviews", "review_reputation", "active_deals", "brand_assets", "source_name", "registry_page", "commercial", "allowed_actions", "requires_human_confirmation", "commercial_disclosure", "citation", "schema_org", "trust_card_url", "public_profile_url" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "registry_name": { "const": "Loppee" }, "subject_kind": { "enum": [ "unclaimed_registry_record", "business_registry_record" ] }, "source_type": { "enum": [ "unclaimed_registry_record", "registry_record" ] }, "claim_status": { "enum": [ "unclaimed", "owner_submitted", "claimed" ] }, "disclosure": { "enum": [ "Registry record. Not a claimed Loppee business customer.", "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee.", "Claimed business profile. Not yet published as Verified or Listed on Loppee." ] }, "business_id": { "type": "string" }, "display_name": { "type": "string" }, "legal_name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "primary_category": { "type": [ "string", "null" ] }, "category": { "type": "array", "items": { "type": "string" } }, "services": { "type": "array", "items": { "type": "string" } }, "service_areas": { "type": "array", "items": { "type": "string" } }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "locations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "label", "street_address", "city", "state", "zip", "is_primary" ], "properties": { "label": { "type": "string" }, "street_address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "is_primary": { "type": "boolean" }, "reach_radius_miles": { "type": "number", "minimum": 0 } } } }, "hours": { "type": [ "object", "null" ], "additionalProperties": true }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "rating", "title", "body", "reviewer_name", "created_at", "verification_label", "ranking_weight", "relationship", "service_date", "authoring_mode", "agent_assisted", "owner_response", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "id": { "type": "string" }, "rating": { "type": "number", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "reviewer_name": { "type": "string" }, "relationship": { "type": "string" }, "service_date": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "owner_response": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "body", "author_label", "created_at" ], "properties": { "body": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "verification_label": { "enum": [ "Unverified", "Verified interaction" ] }, "ranking_weight": { "enum": [ 0, 1 ] }, "reviewer_verification_label": { "enum": [ "Verified reviewer", "Unverified reviewer" ] }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "enum": [ 0, 1 ] } }, "allOf": [ { "if": { "properties": { "verification_label": { "const": "Verified interaction" } }, "required": [ "verification_label" ] }, "then": { "properties": { "ranking_weight": { "const": 1 } } }, "else": { "properties": { "ranking_weight": { "const": 0 } } } }, { "if": { "properties": { "reviewer_verification_label": { "const": "Verified reviewer" } }, "required": [ "reviewer_verification_label" ] }, "then": { "properties": { "quality_ranking_weight": { "const": 1 } } }, "else": { "properties": { "quality_ranking_weight": { "const": 0 } } } } ] } }, "review_reputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating", "reviews_url" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "active_deals": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "description", "discount", "promo_code", "terms", "starts_at", "expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "discount": { "type": "string" }, "promo_code": { "type": "string" }, "terms": { "type": "string" }, "starts_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } } } }, "insurance": { "type": "object", "additionalProperties": false, "required": [ "status", "carrier_name", "stated_expires_at", "disclosure" ], "properties": { "status": { "const": "owner_provided" }, "carrier_name": { "const": "Not publicly disclosed" }, "stated_expires_at": { "type": [ "string", "null" ] }, "disclosure": { "const": "Insurance certificate provided by the business. Not independently confirmed by Loppee." } } }, "brand_assets": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, { "type": "null" } ] }, "source_name": { "type": [ "string", "null" ] }, "registry_page": { "type": "object", "additionalProperties": false, "required": [ "claim_prompt", "reviews_notice", "reviews_enabled" ], "properties": { "claim_prompt": { "type": "string" }, "reviews_notice": { "const": "Reviews from identity-verified reviewers can influence search and recommendation quality. They do not verify, claim, or publish this business, and they do not prove a transaction." }, "reviews_enabled": { "type": "boolean" } } }, "commercial": { "type": "object", "additionalProperties": false, "required": [ "status", "exposure_tier", "sponsored", "influence", "sponsored_ordering", "free_exposure_floor" ], "properties": { "status": { "const": "free" }, "exposure_tier": { "const": "free" }, "sponsored": { "const": false }, "influence": { "const": "none" }, "sponsored_ordering": { "const": "disabled" }, "free_exposure_floor": { "type": "null" } } }, "allowed_actions": { "type": "array", "items": { "type": "string" } }, "requires_human_confirmation": { "type": "array", "items": { "type": "string" } }, "commercial_disclosure": { "const": "Exposure-plan payment changes discovery reach, gallery capacity, and, when Sponsored ordering is active, labeled position-weighted exposure only within the same verification class and verified-review reputation band. It never changes business-profile publication, verification, review authority, reputation, moderation, class ordering, or reputation band. Loppee Jobs is a separate optional paid product; its billing affects job-posting activation only and never business verification or directory ranking." }, "citation": { "type": "object", "additionalProperties": false, "required": [ "registry", "url" ], "properties": { "registry": { "type": "string" }, "url": { "type": "string" } } }, "schema_org": { "type": "object", "additionalProperties": false, "required": [ "@context", "@type", "name", "url", "additionalProperty" ], "properties": { "@context": { "const": "https://schema.org" }, "@type": { "const": "LocalBusiness" }, "name": { "type": "string" }, "url": { "type": "string" }, "telephone": { "type": "string" }, "address": { "type": "object", "additionalProperties": false, "required": [ "@type", "addressCountry" ], "properties": { "@type": { "const": "PostalAddress" }, "streetAddress": { "type": "string" }, "addressLocality": { "type": "string" }, "addressRegion": { "type": "string" }, "postalCode": { "type": "string" }, "addressCountry": { "const": "US" } } }, "additionalProperty": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "@type", "name", "value" ], "properties": { "@type": { "const": "PropertyValue" }, "name": { "enum": [ "loppee_subject_kind", "loppee_registry_disclosure" ] }, "value": { "type": "string" } } } } } }, "trust_card_url": { "type": "string" }, "public_profile_url": { "type": "string" }, "updated_at": { "type": "string" } }, "allOf": [ { "oneOf": [ { "required": [ "subject_kind", "source_type", "claim_status", "disclosure" ], "properties": { "subject_kind": { "const": "unclaimed_registry_record" }, "source_type": { "const": "unclaimed_registry_record" }, "claim_status": { "const": "unclaimed" }, "disclosure": { "const": "Registry record. Not a claimed Loppee business customer." } } }, { "required": [ "subject_kind", "source_type", "claim_status", "disclosure" ], "properties": { "subject_kind": { "const": "business_registry_record" }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "owner_submitted" }, "disclosure": { "const": "Claim submitted. Ownership review is pending; this business is not yet published as Verified or Listed on Loppee." } } }, { "required": [ "subject_kind", "source_type", "claim_status", "disclosure" ], "properties": { "subject_kind": { "const": "business_registry_record" }, "source_type": { "const": "registry_record" }, "claim_status": { "const": "claimed" }, "disclosure": { "const": "Claimed business profile. Not yet published as Verified or Listed on Loppee." } } } ] } ] }, "PublishedBusinessReviewsResponse": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "trust_model_version", "registry_name", "business_id", "display_name", "policy", "sort", "filter", "summary", "reviews", "pagination" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "registry_name": { "const": "Loppee" }, "business_id": { "type": "string" }, "display_name": { "type": "string" }, "policy": { "type": "string" }, "sort": { "const": "newest_first" }, "filter": { "type": "object", "additionalProperties": false, "required": [ "ratings" ], "properties": { "ratings": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1, "maximum": 5 } } } }, "summary": { "type": "object", "additionalProperties": false, "required": [ "average_rating", "review_count", "verified_review_count", "rating_counts", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "average_rating": { "type": [ "number", "null" ] }, "review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "rating_counts": { "type": "object", "additionalProperties": false, "required": [ "1", "2", "3", "4", "5" ], "properties": { "1": { "type": "integer", "minimum": 0 }, "2": { "type": "integer", "minimum": 0 }, "3": { "type": "integer", "minimum": 0 }, "4": { "type": "integer", "minimum": 0 }, "5": { "type": "integer", "minimum": 0 } } }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "counts_truncated": { "type": "boolean" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "rating", "title", "body", "reviewer_name", "created_at", "verification_label", "ranking_weight", "relationship", "service_date", "authoring_mode", "agent_assisted", "owner_response", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "id": { "type": "string" }, "rating": { "type": "number", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "reviewer_name": { "type": "string" }, "relationship": { "type": "string" }, "service_date": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "owner_response": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "body", "author_label", "created_at" ], "properties": { "body": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "verification_label": { "enum": [ "Unverified", "Verified interaction" ] }, "ranking_weight": { "enum": [ 0, 1 ] }, "reviewer_verification_label": { "enum": [ "Verified reviewer", "Unverified reviewer" ] }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "enum": [ 0, 1 ] } }, "allOf": [ { "if": { "properties": { "verification_label": { "const": "Verified interaction" } }, "required": [ "verification_label" ] }, "then": { "properties": { "ranking_weight": { "const": 1 } } }, "else": { "properties": { "ranking_weight": { "const": 0 } } } }, { "if": { "properties": { "reviewer_verification_label": { "const": "Verified reviewer" } }, "required": [ "reviewer_verification_label" ] }, "then": { "properties": { "quality_ranking_weight": { "const": 1 } } }, "else": { "properties": { "quality_ranking_weight": { "const": 0 } } } } ] } }, "pagination": { "type": "object", "additionalProperties": false, "required": [ "page", "limit", "total_count", "total_pages", "has_more", "next_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "total_count": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "next_page": { "type": [ "integer", "null" ], "minimum": 1 } } } } }, "RegistryBusinessReviewsResponse": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "trust_model_version", "registry_name", "business_id", "display_name", "policy", "sort", "filter", "summary", "reviews", "pagination", "business_claim_status", "registry_page_notice" ], "properties": { "schema_version": { "const": "3.0" }, "trust_model_version": { "const": "v3" }, "registry_name": { "const": "Loppee" }, "business_id": { "type": "string" }, "display_name": { "type": "string" }, "policy": { "type": "string" }, "sort": { "const": "newest_first" }, "filter": { "type": "object", "additionalProperties": false, "required": [ "ratings" ], "properties": { "ratings": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 1, "maximum": 5 } } } }, "summary": { "type": "object", "additionalProperties": false, "required": [ "average_rating", "review_count", "verified_review_count", "rating_counts", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "average_rating": { "type": [ "number", "null" ] }, "review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "rating_counts": { "type": "object", "additionalProperties": false, "required": [ "1", "2", "3", "4", "5" ], "properties": { "1": { "type": "integer", "minimum": 0 }, "2": { "type": "integer", "minimum": 0 }, "3": { "type": "integer", "minimum": 0 }, "4": { "type": "integer", "minimum": 0 }, "5": { "type": "integer", "minimum": 0 } } }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "counts_truncated": { "type": "boolean" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "rating", "title", "body", "reviewer_name", "created_at", "verification_label", "ranking_weight", "relationship", "service_date", "authoring_mode", "agent_assisted", "owner_response", "reviewer_verification_label", "reviewer_verification_disclosure", "quality_ranking_weight" ], "properties": { "id": { "type": "string" }, "rating": { "type": "number", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "body": { "type": "string" }, "reviewer_name": { "type": "string" }, "relationship": { "type": "string" }, "service_date": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "authoring_mode": { "enum": [ "human", "customer_agent" ] }, "agent_assisted": { "type": "boolean" }, "owner_response": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "body", "author_label", "created_at" ], "properties": { "body": { "type": "string" }, "author_label": { "type": "string" }, "created_at": { "type": "string" } } }, { "type": "null" } ] }, "verification_label": { "enum": [ "Unverified", "Verified interaction" ] }, "ranking_weight": { "enum": [ 0, 1 ] }, "reviewer_verification_label": { "enum": [ "Verified reviewer", "Unverified reviewer" ] }, "reviewer_verification_disclosure": { "const": "Verified reviewer means the registered account completed Passkey or phone verification. It does not prove a transaction or government identity." }, "quality_ranking_weight": { "enum": [ 0, 1 ] } }, "allOf": [ { "if": { "properties": { "verification_label": { "const": "Verified interaction" } }, "required": [ "verification_label" ] }, "then": { "properties": { "ranking_weight": { "const": 1 } } }, "else": { "properties": { "ranking_weight": { "const": 0 } } } }, { "if": { "properties": { "reviewer_verification_label": { "const": "Verified reviewer" } }, "required": [ "reviewer_verification_label" ] }, "then": { "properties": { "quality_ranking_weight": { "const": 1 } } }, "else": { "properties": { "quality_ranking_weight": { "const": 0 } } } } ] } }, "pagination": { "type": "object", "additionalProperties": false, "required": [ "page", "limit", "total_count", "total_pages", "has_more", "next_page" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "total_count": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "next_page": { "type": [ "integer", "null" ], "minimum": 1 } } }, "business_claim_status": { "enum": [ "unclaimed", "owner_submitted", "claimed" ] }, "registry_page_notice": { "const": "Reviews from identity-verified reviewers can influence search and recommendation quality. They do not verify, claim, or publish this business, and they do not prove a transaction." } }, "title": "Loppee v3 Registry business reviews with reviewer quality" }, "V3BrandAssets": { "type": "object", "additionalProperties": false, "required": [ "logo_url", "hero_image_url", "gallery_image_urls", "hero_alt", "source" ], "properties": { "logo_url": { "type": [ "string", "null" ] }, "hero_image_url": { "type": [ "string", "null" ] }, "gallery_image_urls": { "type": "array", "items": { "type": "string" } }, "hero_alt": { "type": "string" }, "source": { "type": "string" } } }, "ReviewReputation": { "type": "object", "additionalProperties": false, "required": [ "display_rating", "display_review_count", "verified_review_count", "ranking", "identity_verified_review_count", "quality_rating" ], "properties": { "display_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "display_review_count": { "type": "integer", "minimum": 0 }, "verified_review_count": { "type": "integer", "minimum": 0 }, "ranking": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } ] }, "latest_review_snippet": { "type": [ "string", "null" ] }, "counts_truncated": { "type": "boolean" }, "reviews_url": { "type": "string" }, "identity_verified_review_count": { "type": "integer", "minimum": 0 }, "quality_rating": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 } }, "allOf": [ { "if": { "properties": { "identity_verified_review_count": { "minimum": 1 } }, "required": [ "identity_verified_review_count" ] }, "then": { "properties": { "quality_rating": { "type": "number", "minimum": 1, "maximum": 5 }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "quality_ranked" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "number", "minimum": 1, "maximum": 5, "multipleOf": 0.5 }, "explanation": { "const": "Ratings from identity-verified reviewers influence quality ordering within the applicable business class or Registry pool. They do not verify the business, prove a transaction, change discovery reach, or permit paid influence." } } } } }, "else": { "properties": { "quality_rating": { "type": "null" }, "ranking": { "type": "object", "additionalProperties": false, "required": [ "status", "basis", "half_star_band", "explanation" ], "properties": { "status": { "const": "unrated" }, "basis": { "const": "identity_verified_reviewer_reviews" }, "half_star_band": { "type": "null" }, "explanation": { "const": "No identity-verified reviewer rating is available. There is no reviewer-quality ranking signal for this business." } } } } } } ] }, "ExternalAgentWebhookPayload": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "event_id", "event_type", "occurred_at", "recipient", "resource" ], "properties": { "schema_version": { "const": "external-agent-webhook.v1" }, "event_id": { "type": "string", "minLength": 1, "maxLength": 240 }, "event_type": { "type": "string", "enum": [ "business.message.replied", "customer.message.created", "admin.verification_submission.created", "agent.webhook.test" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "recipient": { "type": "object", "additionalProperties": false, "required": [ "scope_kind", "account_id", "business_id" ], "properties": { "scope_kind": { "type": "string", "enum": [ "consumer", "management", "team" ] }, "account_id": { "type": "string", "minLength": 1, "maxLength": 240 }, "business_id": { "type": [ "string", "null" ], "maxLength": 240 } } }, "resource": { "type": "object", "additionalProperties": false, "required": [ "kind", "id", "conversation_id" ], "properties": { "kind": { "type": "string", "minLength": 1, "maxLength": 120 }, "id": { "type": "string", "minLength": 1, "maxLength": 240 }, "conversation_id": { "type": [ "string", "null" ], "maxLength": 240 } } } } }, "CustomerLocationProofRequest": { "type": "object", "additionalProperties": false, "required": [ "latitude", "longitude", "accuracy_meters", "captured_at" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_meters": { "type": "number", "exclusiveMinimum": 0, "maximum": 500 }, "captured_at": { "type": "string", "format": "date-time" } } }, "CustomerLocationProofResponse": { "type": "object", "additionalProperties": false, "required": [ "location_proof_id", "status", "usable_until", "uses_remaining", "coordinates_returned" ], "properties": { "location_proof_id": { "type": "string", "format": "uuid" }, "status": { "const": "ready" }, "usable_until": { "type": "string", "format": "date-time" }, "uses_remaining": { "type": "integer", "minimum": 0, "maximum": 20 }, "coordinates_returned": { "const": false } } }, "CustomerLocationProofRevocationResponse": { "type": "object", "additionalProperties": false, "required": [ "location_proof_id", "status", "revoked", "coordinates_returned" ], "properties": { "location_proof_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "revoked", "expired", "used_up" ] }, "revoked": { "type": "boolean" }, "coordinates_returned": { "const": false } } }, "LocationHandoffCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "handoff_id", "location_kind", "status", "approval_expires_at", "poll_after_seconds", "next_action", "agent_receives_coordinates" ], "properties": { "handoff_id": { "type": "string", "format": "uuid" }, "location_kind": { "enum": [ "current", "destination" ] }, "status": { "const": "awaiting_user" }, "location_url": { "type": "string", "format": "uri" }, "approval_expires_at": { "type": "string", "format": "date-time" }, "poll_after_seconds": { "type": "integer", "minimum": 1 }, "request_mode": { "enum": [ "automatic", "approval_required" ] }, "next_action": { "enum": [ "poll_location_handoff", "open_loppee_phone_app", "ask_user_to_open_location_url" ] }, "agent_receives_coordinates": { "const": false } }, "oneOf": [ { "properties": { "location_kind": { "const": "current" }, "next_action": { "enum": [ "poll_location_handoff", "open_loppee_phone_app" ] } }, "required": [ "location_kind", "next_action", "request_mode" ], "not": { "required": [ "location_url" ] } }, { "properties": { "location_kind": { "const": "destination" }, "next_action": { "const": "ask_user_to_open_location_url" } }, "required": [ "location_kind", "next_action", "location_url" ], "not": { "required": [ "request_mode" ] } } ] }, "LocationHandoffStatusResponse": { "type": "object", "additionalProperties": false, "required": [ "handoff_id", "location_kind", "status", "approval_expires_at", "usable_until", "uses_remaining", "next_action", "agent_receives_coordinates" ], "properties": { "handoff_id": { "type": "string", "format": "uuid" }, "location_kind": { "enum": [ "current", "destination" ] }, "status": { "enum": [ "awaiting_user", "ready", "declined", "expired", "used_up", "revoked" ] }, "approval_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "usable_until": { "type": [ "string", "null" ], "format": "date-time" }, "uses_remaining": { "type": "integer", "minimum": 0 }, "next_action": { "enum": [ "search_with_location_handoff", "wait_for_iphone_location", "open_loppee_phone_app", "wait_for_user_approval", "ask_user_to_open_location_url", "create_new_location_handoff", "continue_without_precise_location" ] }, "request_mode": { "enum": [ "automatic", "approval_required" ] }, "location_url": { "type": "string", "format": "uri" }, "agent_receives_coordinates": { "const": false } }, "oneOf": [ { "properties": { "location_kind": { "const": "current" }, "next_action": { "enum": [ "search_with_location_handoff", "wait_for_iphone_location", "open_loppee_phone_app", "create_new_location_handoff", "continue_without_precise_location" ] } }, "required": [ "location_kind", "next_action", "request_mode" ], "not": { "required": [ "location_url" ] } }, { "properties": { "location_kind": { "const": "destination" }, "next_action": { "const": "ask_user_to_open_location_url" } }, "required": [ "location_kind", "next_action", "location_url" ], "not": { "required": [ "request_mode" ] } }, { "properties": { "location_kind": { "const": "destination" }, "next_action": { "enum": [ "search_with_location_handoff", "wait_for_user_approval", "create_new_location_handoff", "continue_without_precise_location" ] } }, "required": [ "location_kind", "next_action" ], "not": { "anyOf": [ { "required": [ "location_url" ] }, { "required": [ "request_mode" ] } ] } } ] }, "DestinationAddressSuggestionsRequest": { "type": "object", "additionalProperties": false, "required": [ "input" ], "properties": { "input": { "type": "string", "minLength": 4, "maxLength": 280, "description": "Normalized partial US service-address text. This first-party display request contains no session token, place id, coordinates, or proof authority." } } }, "DestinationAddressSuggestion": { "type": "object", "additionalProperties": false, "required": [ "full_text", "main_text", "secondary_text" ], "properties": { "full_text": { "type": "string", "minLength": 1, "maxLength": 280 }, "main_text": { "type": "string", "minLength": 1, "maxLength": 180 }, "secondary_text": { "type": "string", "maxLength": 220 } } }, "DestinationAddressSuggestionsResponse": { "type": "object", "additionalProperties": false, "required": [ "suggestions" ], "properties": { "suggestions": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/DestinationAddressSuggestion" } } } }, "DestinationLocationProofRequest": { "type": "object", "additionalProperties": false, "required": [ "address" ], "properties": { "address": { "type": "string", "minLength": 5, "maxLength": 280, "description": "A real US service address. It is accepted only in this POST body and is never returned, placed in a URL, or exposed to an external agent." }, "premise_proximity_confirmation_token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Opaque one-time token from the immediately preceding premise-proximity challenge for the same address and authority." } } }, "DestinationLocationProofResponse": { "type": "object", "additionalProperties": false, "required": [ "location_proof_id", "status", "location_kind", "display_label", "usable_until", "uses_remaining", "address_returned", "coordinates_returned" ], "properties": { "location_proof_id": { "type": "string", "format": "uuid" }, "status": { "const": "ready" }, "location_kind": { "const": "destination" }, "display_label": { "const": "Selected service address" }, "usable_until": { "type": "string", "format": "date-time" }, "uses_remaining": { "type": "integer", "minimum": 0, "maximum": 20 }, "address_returned": { "const": false }, "coordinates_returned": { "const": false } } }, "AnonymousLocationProofRequest": { "type": "object", "additionalProperties": false, "required": [ "latitude", "longitude", "accuracy_meters", "captured_at" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "accuracy_meters": { "type": "number", "exclusiveMinimum": 0, "maximum": 500 }, "captured_at": { "type": "string", "format": "date-time" } } }, "AnonymousLocationProofResponse": { "type": "object", "additionalProperties": false, "required": [ "location_proof_id", "status", "usable_until", "uses_remaining", "coordinates_returned" ], "properties": { "location_proof_id": { "type": "string", "format": "uuid" }, "status": { "const": "ready" }, "usable_until": { "type": "string", "format": "date-time" }, "uses_remaining": { "type": "integer", "minimum": 0, "maximum": 20 }, "coordinates_returned": { "const": false } } }, "AnonymousLocationProofRevocationResponse": { "type": "object", "additionalProperties": false, "required": [ "location_proof_id", "status", "revoked", "coordinates_returned" ], "properties": { "location_proof_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "revoked", "expired", "used_up" ] }, "revoked": { "type": "boolean" }, "coordinates_returned": { "const": false } } } } }, "x-loppee-trust-model": "v3", "x-loppee-sponsored-ordering": { "status": "enabled", "model": "sponsored_share_of_voice", "commercial_influence": "sponsored_reach_within_verification_class_and_reputation_band", "free_exposure_floor": 0.25, "requires_precise_location_authority": true, "coarse_context_commercial_influence": "none" }, "x-loppee-local-discovery-location-policy": { "schema_version": "precise-local-discovery.v1", "precise_authorities": [ "current_precise_location", "validated_destination", "saved_exact" ], "coarse_context_sources": [ "city_state", "zip", "provider_ip", "saved_coarse", "caller_supplied_coordinates" ], "coarse_context_allowed_uses": [ "area_context", "name_disambiguation" ], "coarse_context_local_results": false, "coarse_context_commercial_influence": "none", "coarse_context_sponsored_placement": false, "coarse_context_impressions_recorded": false, "connected_assistant_current_handoff_commercial_influence": "none", "connected_assistant_current_handoff_sponsored_placement": false, "connected_assistant_current_handoff_exposure_recorded": false, "connected_assistant_current_handoff_recommendation_attribution_recorded": false, "connected_assistant_current_location_source": "registered_loppee_iphone_only", "connected_assistant_rejected_current_location_sources": [ "provider_ip", "caller_supplied_coordinates", "host_location_metadata", "computer_or_browser_location" ], "universal_name_match_types": [ "exact", "genuine_prefix" ], "universal_name_without_precise_commercial_influence": "none", "universal_name_without_precise_sponsored_placement": false, "destination_result_attribution": { "display_text": "Google Maps", "translate": false, "required_for_location_context_sources": [ "destination_location_handoff", "destination_location_proof" ] }, "statement": "Local category discovery and recommendations require a current precise location proof or handoff, a user-confirmed validated destination authority, or a saved_exact Home location. City/state, ZIP, and saved_coarse locations are neutral area context for business-name disambiguation only: they return no local category or recommendation results, cannot activate Sponsored placement, and record no impressions. A connected assistant's current location comes only from the registered Loppee iPhone; provider IP, caller-supplied coordinates, host metadata, and computer/browser location are rejected as current-location authority. Exact and genuine-prefix business-name lookup remains universal; without precise location it is commercially neutral." }, "webhooks": { "externalAgentWakeUp": { "post": { "operationId": "receiveExternalAgentWakeUp", "summary": "Receive a signed external-agent wake-up event", "description": "Provider-neutral reference-only HTTPS POST from Loppee. The receiver verifies the HMAC and timestamp, deduplicates by event_id or X-Request-ID, and durably accepts the event. For live workflow events it then uses its separate scoped Loppee API/MCP key to fetch the referenced resource. agent.webhook.test is receipt-only and has no fetchable resource. Hermes Generic V2 and any capable customer-operated receiver can implement this wire contract.", "security": [ { "ExternalAgentWebhookHmac": [] } ], "parameters": [ { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "Unix timestamp used in the HMAC signing input.", "schema": { "type": "string", "pattern": "^[0-9]{1,20}$" } }, { "name": "X-Request-ID", "in": "header", "required": true, "description": "Stable delivery id equal to payload event_id; use it to deduplicate retries.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgentWebhookPayload" } } } }, "responses": { "200": { "description": "Event accepted." }, "204": { "description": "Event accepted with no response body." }, "default": { "description": "Non-2xx responses may be retried according to the durable delivery policy. Redirects are not followed." } } } } } }