{
  "components": {
    "responses": {
      "EntitlementRequired": {
        "content": {
          "application/json": {
            "examples": {
              "default": {
                "value": {
                  "code": "entitlement_required",
                  "detail": "the current subscription does not grant access to this product",
                  "status": "403",
                  "title": "Forbidden",
                  "type": "about:blank"
                }
              }
            },
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Valid API key but missing entitlement"
      },
      "Forbidden": {
        "content": {
          "application/json": {
            "examples": {
              "default": {
                "value": {
                  "code": "scope_required",
                  "detail": "the supplied api key does not grant the required scope",
                  "status": "403",
                  "title": "Forbidden",
                  "type": "about:blank"
                }
              }
            },
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Authenticated but not permitted for this route"
      },
      "Unauthorized": {
        "content": {
          "application/json": {
            "examples": {
              "default": {
                "value": {
                  "code": "api_key_required",
                  "detail": "an api key is required",
                  "status": "401",
                  "title": "Unauthorized",
                  "type": "about:blank"
                }
              }
            },
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        },
        "description": "Missing or invalid API key"
      }
    },
    "schemas": {
      "APIKey": {
        "properties": {
          "api_key_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "guardrails": {
            "$ref": "#/components/schemas/APIKeyGuardrails"
          },
          "key_type": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "last_used_at": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "project_environment_id": {
            "type": "string"
          },
          "project_environment_name": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "service_account": {
            "$ref": "#/components/schemas/ServiceAccountProfile"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "APIKeyGuardrails": {
        "properties": {
          "alert_threshold_percent": {
            "type": "integer"
          },
          "enforcement_mode": {
            "type": "string"
          },
          "monthly_quota_requests": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "AgentQueryConstraint": {
        "properties": {
          "code": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "severity": {
            "enum": [
              "advisory",
              "warning"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "AgentQueryRecommendation": {
        "properties": {
          "confidence": {
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "type": "string"
          },
          "family": {
            "type": "string"
          },
          "mcp_tool": {
            "type": "string"
          },
          "missing_scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "reason": {
            "type": "string"
          },
          "required_scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "rest_route": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AgentQueryRequest": {
        "properties": {
          "available_scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "location_id": {
            "type": "string"
          },
          "preferred_protocol": {
            "enum": [
              "rest",
              "mcp"
            ],
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          }
        },
        "required": [
          "query"
        ],
        "type": "object"
      },
      "AgentQueryResponse": {
        "properties": {
          "constraint_reported": {
            "type": "boolean"
          },
          "constraints": {
            "items": {
              "$ref": "#/components/schemas/AgentQueryConstraint"
            },
            "type": "array"
          },
          "deterministic_key": {
            "type": "string"
          },
          "normalized_query": {
            "type": "string"
          },
          "planning_version": {
            "type": "string"
          },
          "preferred_protocol": {
            "type": "string"
          },
          "recommendations": {
            "items": {
              "$ref": "#/components/schemas/AgentQueryRecommendation"
            },
            "type": "array"
          },
          "recommended_family": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AttributionRecord": {
        "properties": {
          "attribution_id": {
            "type": "string"
          },
          "attribution_lines": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "dataset_name": {
            "type": "string"
          },
          "last_refreshed_at": {
            "type": "string"
          },
          "licence_url": {
            "type": "string"
          },
          "module": {
            "type": "string"
          },
          "publisher_name": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "source_url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AuditEvent": {
        "properties": {
          "actor_id": {
            "type": "string"
          },
          "actor_type": {
            "type": "string"
          },
          "audit_event_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "event_payload": {
            "type": "object"
          },
          "event_type": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AuditExport": {
        "properties": {
          "export_id": {
            "type": "string"
          },
          "format": {
            "type": "string"
          },
          "generated_at": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "record_count": {
            "type": "integer"
          },
          "records": {
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "AuditExportRequest": {
        "properties": {
          "format": {
            "description": "Optional export format (`json`, `jsonl`, or `csv`).",
            "type": "string"
          }
        },
        "type": "object"
      },
      "BillingEvent": {
        "properties": {
          "created_at": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "BillingInvoice": {
        "properties": {
          "amount_due": {
            "type": "integer"
          },
          "amount_paid": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "discount_amount": {
            "type": "integer"
          },
          "due_at": {
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "issued_at": {
            "type": "string"
          },
          "period_end": {
            "type": "string"
          },
          "period_start": {
            "type": "string"
          },
          "source_of_truth": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "subscription_id": {
            "type": "string"
          },
          "subtotal": {
            "type": "integer"
          },
          "tax_amount": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "BillingLifecycle": {
        "properties": {
          "access_state": {
            "type": "string"
          },
          "cancel_at": {
            "type": "string"
          },
          "current_period_end": {
            "type": "string"
          },
          "dunning_state": {
            "type": "string"
          },
          "entitlement_state": {
            "type": "string"
          },
          "grace_period_ends_at": {
            "type": "string"
          },
          "latest_invoice_status": {
            "type": "string"
          },
          "manage_billing_message": {
            "type": "string"
          },
          "next_invoice_at": {
            "type": "string"
          },
          "trial_ends_at": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CapabilitiesResponse": {
        "properties": {
          "auth_methods": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "capability_version": {
            "type": "string"
          },
          "discovery_endpoints": {
            "items": {
              "$ref": "#/components/schemas/DiscoveryEndpoint"
            },
            "type": "array"
          },
          "domains": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "example_recipes": {
            "items": {
              "$ref": "#/components/schemas/ExampleRecipe"
            },
            "type": "array"
          },
          "family_capabilities": {
            "items": {
              "$ref": "#/components/schemas/FamilyCapability"
            },
            "type": "array"
          },
          "legal_posture": {
            "type": "string"
          },
          "mcp_tooling": {
            "$ref": "#/components/schemas/MCPTooling"
          },
          "planned_domains": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "positioning": {
            "type": "string"
          },
          "protocols": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "service": {
            "type": "string"
          },
          "supported_queries": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "tagline": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CatalogEntry": {
        "properties": {
          "billing_interval": {
            "type": "string"
          },
          "checkout_enabled": {
            "type": "boolean"
          },
          "currencies": {
            "items": {
              "properties": {
                "currency": {
                  "type": "string"
                },
                "monthly_quota": {
                  "type": "integer"
                },
                "unit_amount": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "description": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "included_products": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "launch_region_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "plan_code": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CheckoutRequest": {
        "properties": {
          "automatic_tax": {
            "type": "boolean"
          },
          "billing_country": {
            "type": "string"
          },
          "cancel_url": {
            "type": "string"
          },
          "coupon_code": {
            "type": "string"
          },
          "currency": {
            "description": "Optional. Defaults to `usd` when omitted.",
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "overage_alert_threshold_percent": {
            "type": "integer"
          },
          "overage_cap_requests": {
            "type": "integer"
          },
          "overage_mode": {
            "type": "string"
          },
          "plan_code": {
            "type": "string"
          },
          "success_url": {
            "type": "string"
          },
          "tax_exempt": {
            "type": "string"
          },
          "trial_days": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "CheckoutSessionResponse": {
        "properties": {
          "id": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CivicAppliedFilters": {
        "properties": {
          "limit": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CivicServicePoint": {
        "properties": {
          "address_line_1": {
            "type": "string"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "department_name": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "municipality": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "privacy_review_status": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "service_category": {
            "type": "string"
          },
          "service_name_en": {
            "type": "string"
          },
          "service_name_fr": {
            "type": "string"
          },
          "service_point_id": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "website_url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CivicServicePointListResponse": {
        "properties": {
          "applied_filters": {
            "$ref": "#/components/schemas/CivicAppliedFilters"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/CivicServicePoint"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CommercialAnalytics": {
        "properties": {
          "data_limitations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "recommendations": {
            "items": {
              "$ref": "#/components/schemas/ExpansionRecommendation"
            },
            "type": "array"
          },
          "spend": {
            "$ref": "#/components/schemas/SpendSummary"
          },
          "usage_breakdown": {
            "$ref": "#/components/schemas/UsageBreakdown"
          }
        },
        "type": "object"
      },
      "ContextResponse": {
        "properties": {
          "agent_summary": {
            "type": "string"
          },
          "air_quality": {
            "type": "string"
          },
          "anchor_city": {
            "type": "string"
          },
          "business_density": {
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "legal_notice": {
            "type": "string"
          },
          "location_id": {
            "type": "string"
          },
          "population": {
            "$ref": "#/components/schemas/PopulationContext"
          },
          "recommended_queries": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "recommended_use_cases": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "region_id": {
            "type": "string"
          },
          "source_dataset_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "summary_status": {
            "type": "string"
          },
          "supported_modules": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "timezone": {
            "type": "string"
          },
          "transit_systems": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "weather_profile": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CoverageRegion": {
        "properties": {
          "anchor_municipalities": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "country_code": {
            "type": "string"
          },
          "coverage": {
            "properties": {
              "civic": {
                "type": "string"
              },
              "environment": {
                "type": "string"
              },
              "places": {
                "type": "string"
              },
              "products": {
                "type": "string"
              },
              "regulatory": {
                "type": "string"
              },
              "transit": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "coverage_vocabulary": {
            "properties": {
              "limited": {
                "type": "string"
              },
              "planned": {
                "type": "string"
              },
              "ready": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "display_name_en": {
            "type": "string"
          },
          "display_name_fr": {
            "type": "string"
          },
          "geography_type": {
            "type": "string"
          },
          "module_freshness": {
            "additionalProperties": {
              "properties": {
                "expected_refresh_cadence": {
                  "type": "string"
                },
                "freshness_state": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "object"
          },
          "region_id": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CreateAPIKeyRequest": {
        "properties": {
          "label": {
            "type": "string"
          },
          "project_environment_id": {
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "CreateServiceAccountRequest": {
        "properties": {
          "label": {
            "type": "string"
          },
          "project_environment_id": {
            "type": "string"
          },
          "rotation_interval_days": {
            "type": "integer"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "DashboardSummary": {
        "properties": {
          "api_keys": {
            "items": {
              "$ref": "#/components/schemas/APIKey"
            },
            "type": "array"
          },
          "audit_events": {
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "type": "array"
          },
          "billing_history": {
            "items": {
              "$ref": "#/components/schemas/BillingEvent"
            },
            "type": "array"
          },
          "billing_lifecycle": {
            "$ref": "#/components/schemas/BillingLifecycle"
          },
          "commercial_analytics": {
            "$ref": "#/components/schemas/CommercialAnalytics"
          },
          "entitlements": {
            "items": {
              "$ref": "#/components/schemas/Entitlement"
            },
            "type": "array"
          },
          "invitations": {
            "items": {
              "$ref": "#/components/schemas/Invitation"
            },
            "type": "array"
          },
          "invoices": {
            "items": {
              "$ref": "#/components/schemas/BillingInvoice"
            },
            "type": "array"
          },
          "manage_billing_ok": {
            "type": "boolean"
          },
          "members": {
            "items": {
              "$ref": "#/components/schemas/OrgMember"
            },
            "type": "array"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "overage": {
            "$ref": "#/components/schemas/OverageSummary"
          },
          "plan_catalog": {
            "items": {
              "$ref": "#/components/schemas/CatalogEntry"
            },
            "type": "array"
          },
          "plan_limits": {
            "items": {
              "$ref": "#/components/schemas/PlanLimit"
            },
            "type": "array"
          },
          "project_environments": {
            "items": {
              "$ref": "#/components/schemas/ProjectEnvironment"
            },
            "type": "array"
          },
          "service_accounts": {
            "items": {
              "$ref": "#/components/schemas/APIKey"
            },
            "type": "array"
          },
          "subscription": {
            "$ref": "#/components/schemas/Subscription"
          },
          "support_bundles": {
            "items": {
              "$ref": "#/components/schemas/SupportBundle"
            },
            "type": "array"
          },
          "support_tickets": {
            "items": {
              "$ref": "#/components/schemas/SupportTicket"
            },
            "type": "array"
          },
          "usage": {
            "$ref": "#/components/schemas/UsageSummary"
          }
        },
        "type": "object"
      },
      "DiscoveryEndpoint": {
        "properties": {
          "auth": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "path": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Entitlement": {
        "properties": {
          "effective_at": {
            "type": "string"
          },
          "entitlement_id": {
            "type": "string"
          },
          "expires_at": {
            "type": "string"
          },
          "feature_code": {
            "type": "string"
          },
          "product_code": {
            "type": "string"
          },
          "source_subscription_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnvironmentAlert": {
        "properties": {
          "alert_id": {
            "type": "string"
          },
          "alert_type": {
            "type": "string"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "headline_en": {
            "type": "string"
          },
          "headline_fr": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "operational_status": {
            "type": "string"
          },
          "publisher_name": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "summary_en": {
            "type": "string"
          },
          "summary_fr": {
            "type": "string"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "valid_from": {
            "type": "string"
          },
          "valid_until": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnvironmentAlertListResponse": {
        "properties": {
          "applied_filters": {
            "$ref": "#/components/schemas/EnvironmentAppliedFilters"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/EnvironmentAlert"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnvironmentAppliedFilters": {
        "properties": {
          "limit": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnvironmentUsage": {
        "properties": {
          "active_key_count": {
            "type": "integer"
          },
          "project_environment_id": {
            "type": "string"
          },
          "project_environment_name": {
            "type": "string"
          },
          "request_count": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "EnvironmentUsageShare": {
        "properties": {
          "active_key_count": {
            "type": "integer"
          },
          "project_environment_id": {
            "type": "string"
          },
          "project_environment_name": {
            "type": "string"
          },
          "request_count": {
            "type": "integer"
          },
          "share_percent": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ErrorResponse": {
        "properties": {
          "code": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ExampleRecipe": {
        "properties": {
          "description": {
            "type": "string"
          },
          "languages": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ExpansionRecommendation": {
        "properties": {
          "action_hint": {
            "type": "string"
          },
          "action_label": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "priority": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "why_now": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "FamilyCapability": {
        "properties": {
          "description": {
            "type": "string"
          },
          "example_recipe": {
            "type": "string"
          },
          "family": {
            "type": "string"
          },
          "mcp_detail_tool": {
            "type": "string"
          },
          "mcp_search_tool": {
            "type": "string"
          },
          "required_scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "rest_base_path": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "IPAllowlistConfiguration": {
        "properties": {
          "cidrs": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "Invitation": {
        "properties": {
          "accepted_at": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "expires_at": {
            "type": "string"
          },
          "invitation_id": {
            "type": "string"
          },
          "invited_by_user_id": {
            "type": "string"
          },
          "membership_role": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "revoked_at": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "IssuedAPIKey": {
        "properties": {
          "api_key_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "raw_key": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ItemsResponse": {
        "properties": {
          "agent_context": {
            "description": "Optional SmartAPIs interpretation block. Source facts remain in entity provenance fields.",
            "type": "object"
          },
          "applied_filters": {
            "properties": {
              "limit": {
                "type": "integer"
              },
              "query": {
                "type": "string"
              },
              "region_id": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "KeyUsage": {
        "properties": {
          "alert_threshold_percent": {
            "type": "integer"
          },
          "alert_triggered": {
            "type": "boolean"
          },
          "api_key_id": {
            "type": "string"
          },
          "enforcement_mode": {
            "type": "string"
          },
          "key_type": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "project_environment_id": {
            "type": "string"
          },
          "project_environment_name": {
            "type": "string"
          },
          "quota_limit": {
            "type": "integer"
          },
          "quota_remaining": {
            "type": "integer"
          },
          "request_count": {
            "type": "integer"
          },
          "role": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "usage_percent": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "KeyUsageShare": {
        "properties": {
          "api_key_id": {
            "type": "string"
          },
          "key_type": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "request_count": {
            "type": "integer"
          },
          "share_percent": {
            "type": "integer"
          },
          "usage_percent": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "MCPTooling": {
        "properties": {
          "authenticated_tip": {
            "type": "string"
          },
          "discovery_tools": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "endpoint_url": {
            "type": "string"
          },
          "protocol_version": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "NearbyPlacesResponse": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/PlacesAgentContextBlock"
          },
          "applied_filters": {
            "properties": {
              "latitude": {
                "type": "number"
              },
              "limit": {
                "type": "integer"
              },
              "longitude": {
                "type": "number"
              },
              "query": {
                "type": "string"
              },
              "radius_km": {
                "type": "number"
              },
              "region_id": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "properties": {
                "category": {
                  "type": "string"
                },
                "display_name_en": {
                  "type": "string"
                },
                "distance_km": {
                  "type": "number"
                },
                "municipality": {
                  "type": "string"
                },
                "place_id": {
                  "type": "string"
                },
                "region_id": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "OpsDatasetFamiliesResponse": {
        "properties": {
          "families": {
            "items": {
              "$ref": "#/components/schemas/OpsDatasetFamily"
            },
            "type": "array"
          },
          "generated_at": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "OpsDatasetFamily": {
        "properties": {
          "family": {
            "type": "string"
          },
          "kill_switch_enabled": {
            "type": "boolean"
          },
          "legal_review_state": {
            "type": "string"
          },
          "sensitive_family": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "OpsFailureResponse": {
        "properties": {
          "failures": {
            "properties": {
              "auth_failures": {
                "additionalProperties": {
                  "type": "integer"
                },
                "type": "object"
              },
              "billing_failures": {
                "additionalProperties": {
                  "type": "integer"
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "generated_at": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "OpsRouteFamily": {
        "properties": {
          "client_error_4xx": {
            "type": "integer"
          },
          "family": {
            "type": "string"
          },
          "last_path": {
            "type": "string"
          },
          "last_request_at": {
            "type": "string"
          },
          "last_status_code": {
            "type": "integer"
          },
          "server_error_5xx": {
            "type": "integer"
          },
          "success_2xx": {
            "type": "integer"
          },
          "total_requests": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "OpsRouteFamilyResponse": {
        "properties": {
          "generated_at": {
            "type": "string"
          },
          "route_families": {
            "items": {
              "$ref": "#/components/schemas/OpsRouteFamily"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "OrgMember": {
        "properties": {
          "created_at": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "membership_id": {
            "type": "string"
          },
          "membership_role": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Organization": {
        "properties": {
          "billing_email": {
            "type": "string"
          },
          "default_currency": {
            "type": "string"
          },
          "default_locale": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "legal_name": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "OverageSummary": {
        "properties": {
          "alert_threshold_percent": {
            "type": "integer"
          },
          "alert_triggered": {
            "type": "boolean"
          },
          "cap_requests": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "enforced": {
            "type": "boolean"
          },
          "estimated_amount": {
            "type": "integer"
          },
          "included_requests": {
            "type": "integer"
          },
          "mode": {
            "type": "string"
          },
          "observed_requests": {
            "type": "integer"
          },
          "overage_requests": {
            "type": "integer"
          },
          "rate_per_1000_requests": {
            "type": "integer"
          },
          "remaining_before_cap": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PlaceAgentContext": {
        "properties": {
          "agent_summary": {
            "type": "string"
          },
          "distance_context": {
            "type": "string"
          },
          "entity": {
            "type": "string"
          },
          "last_reviewed_at": {
            "type": "string"
          },
          "legal_notice": {
            "type": "string"
          },
          "open_now": {
            "type": "boolean"
          },
          "operational_status": {
            "type": "string"
          },
          "place_id": {
            "type": "string"
          },
          "recommended_for": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "region_id": {
            "type": "string"
          },
          "source_confidence": {
            "type": "string"
          },
          "source_fact_boundary": {
            "type": "string"
          },
          "suitability_tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "summary_type": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlaceHours": {
        "properties": {
          "freshness_description": {
            "type": "string"
          },
          "last_reviewed_at": {
            "type": "string"
          },
          "legal_notice": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "place_id": {
            "type": "string"
          },
          "schedule_type": {
            "type": "string"
          },
          "source_confidence": {
            "type": "string"
          },
          "source_type": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "weekly_hours": {
            "items": {
              "properties": {
                "closed": {
                  "type": "boolean"
                },
                "closes_at": {
                  "type": "string"
                },
                "day_of_week": {
                  "type": "string"
                },
                "opens_at": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "PlaceStatus": {
        "properties": {
          "freshness_description": {
            "type": "string"
          },
          "last_reviewed_at": {
            "type": "string"
          },
          "legal_notice": {
            "type": "string"
          },
          "next_change_at": {
            "type": "string"
          },
          "open_now": {
            "type": "boolean"
          },
          "operational_status": {
            "type": "string"
          },
          "place_id": {
            "type": "string"
          },
          "source_confidence": {
            "type": "string"
          },
          "source_type": {
            "type": "string"
          },
          "status_summary": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlaceWatchRequest": {
        "properties": {
          "cadence_hours": {
            "type": "integer"
          },
          "category": {
            "type": "string"
          },
          "delivery_channel": {
            "type": "string"
          },
          "place_id": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlaceWatchResponse": {
        "properties": {
          "bootstrap_limitations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "cadence_hours": {
            "type": "integer"
          },
          "delivery_channel": {
            "type": "string"
          },
          "freshness_description": {
            "type": "string"
          },
          "legal_notice": {
            "type": "string"
          },
          "observed_filter": {
            "$ref": "#/components/schemas/PlaceWatchRequest"
          },
          "product_code": {
            "type": "string"
          },
          "recommended_next_steps": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scope_summary": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          },
          "watch_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlacesAgentContextBlock": {
        "properties": {
          "caution_flags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "interpretation_confidence": {
            "type": "string"
          },
          "source_fact_boundary": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "summary_type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlanLimit": {
        "properties": {
          "product_code": {
            "type": "string"
          },
          "quota_limit": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer"
          },
          "usage_count": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PopulationContext": {
        "properties": {
          "band": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PortalSessionResponse": {
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Product": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/ProductsAgentContextBlock"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "brand": {
            "type": "string"
          },
          "canonical_name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "description_en": {
            "type": "string"
          },
          "display_name_en": {
            "type": "string"
          },
          "gtin": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "mpn": {
            "type": "string"
          },
          "product_id": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "source_dataset": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ProductListResponse": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/ProductsAgentContextBlock"
          },
          "applied_filters": {
            "properties": {
              "brand": {
                "type": "string"
              },
              "gtin": {
                "type": "string"
              },
              "limit": {
                "type": "integer"
              },
              "query": {
                "type": "string"
              },
              "region_id": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/Product"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProductOffer": {
        "properties": {
          "attribution_text": {
            "type": "string"
          },
          "availability": {
            "type": "string"
          },
          "commercial_use_note": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "merchant_domain": {
            "type": "string"
          },
          "merchant_name": {
            "type": "string"
          },
          "offer_id": {
            "type": "string"
          },
          "product_id": {
            "type": "string"
          },
          "product_url": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "unit_amount": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ProductOfferListResponse": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/ProductsAgentContextBlock"
          },
          "as_of": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/ProductOffer"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          },
          "product_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProductPriceHistoryResponse": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/ProductsAgentContextBlock"
          },
          "count": {
            "type": "integer"
          },
          "legal_notice": {
            "type": "string"
          },
          "points": {
            "items": {
              "$ref": "#/components/schemas/ProductPricePoint"
            },
            "type": "array"
          },
          "product_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProductPricePoint": {
        "properties": {
          "availability": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "merchant_count": {
            "type": "integer"
          },
          "observed_at": {
            "type": "string"
          },
          "product_id": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "unit_amount": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ProductUsageShare": {
        "properties": {
          "product_code": {
            "type": "string"
          },
          "request_count": {
            "type": "integer"
          },
          "share_percent": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ProductWatchRequest": {
        "properties": {
          "brand": {
            "type": "string"
          },
          "cadence_hours": {
            "type": "integer"
          },
          "delivery_channel": {
            "type": "string"
          },
          "gtin": {
            "type": "string"
          },
          "product_id": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProductWatchResponse": {
        "properties": {
          "bootstrap_limitations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "cadence_hours": {
            "type": "integer"
          },
          "delivery_channel": {
            "type": "string"
          },
          "freshness_description": {
            "type": "string"
          },
          "legal_notice": {
            "type": "string"
          },
          "observed_filter": {
            "$ref": "#/components/schemas/ProductWatchRequest"
          },
          "product_code": {
            "type": "string"
          },
          "recommended_next_steps": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scope_summary": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          },
          "watch_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProductsAgentContextBlock": {
        "properties": {
          "caution_flags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "interpretation_confidence": {
            "type": "string"
          },
          "source_fact_boundary": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "summary_type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProjectEnvironment": {
        "properties": {
          "description": {
            "type": "string"
          },
          "is_default": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "project_environment_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryAgentContextBlock": {
        "properties": {
          "caution_flags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "interpretation_confidence": {
            "type": "string"
          },
          "source_fact_boundary": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "summary_type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryAppliedFilters": {
        "properties": {
          "limit": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryFacility": {
        "properties": {
          "address_line_1": {
            "type": "string"
          },
          "advisory_boundary_notice": {
            "type": "string"
          },
          "agent_context": {
            "$ref": "#/components/schemas/RegulatoryAgentContextBlock"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "entity_type": {
            "type": "string"
          },
          "facility_category": {
            "type": "string"
          },
          "facility_id": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "municipality": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "privacy_review_status": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "website_url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryInspectionListResponse": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/RegulatoryAgentContextBlock"
          },
          "applied_filters": {
            "$ref": "#/components/schemas/RegulatoryAppliedFilters"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/RegulatoryInspectionRecord"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryInspectionRecord": {
        "properties": {
          "advisory_boundary_notice": {
            "type": "string"
          },
          "agent_context": {
            "$ref": "#/components/schemas/RegulatoryAgentContextBlock"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "facility_id": {
            "type": "string"
          },
          "inspection_date": {
            "type": "string"
          },
          "inspection_program": {
            "type": "string"
          },
          "inspection_status": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "municipality": {
            "type": "string"
          },
          "record_id": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "score": {
            "type": "integer"
          },
          "severity": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "subject_name": {
            "type": "string"
          },
          "summary_en": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryLicenseListResponse": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/RegulatoryAgentContextBlock"
          },
          "applied_filters": {
            "$ref": "#/components/schemas/RegulatoryAppliedFilters"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/RegulatoryLicenseRecord"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryLicenseRecord": {
        "properties": {
          "advisory_boundary_notice": {
            "type": "string"
          },
          "agent_context": {
            "$ref": "#/components/schemas/RegulatoryAgentContextBlock"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "expiry_date": {
            "type": "string"
          },
          "facility_id": {
            "type": "string"
          },
          "issue_date": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_status": {
            "type": "string"
          },
          "license_type": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "municipality": {
            "type": "string"
          },
          "record_id": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "subject_name": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryPermitListResponse": {
        "properties": {
          "agent_context": {
            "$ref": "#/components/schemas/RegulatoryAgentContextBlock"
          },
          "applied_filters": {
            "$ref": "#/components/schemas/RegulatoryAppliedFilters"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/RegulatoryPermitRecord"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryPermitRecord": {
        "properties": {
          "advisory_boundary_notice": {
            "type": "string"
          },
          "agent_context": {
            "$ref": "#/components/schemas/RegulatoryAgentContextBlock"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "facility_id": {
            "type": "string"
          },
          "filed_date": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "municipality": {
            "type": "string"
          },
          "permit_status": {
            "type": "string"
          },
          "permit_type": {
            "type": "string"
          },
          "record_id": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "subject_name": {
            "type": "string"
          },
          "updated_date": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatorySiteBriefAppliedFilters": {
        "properties": {
          "facility_id": {
            "type": "string"
          },
          "limit": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatorySiteBriefFamilyNotices": {
        "properties": {
          "environment": {
            "type": "string"
          },
          "regulatory": {
            "type": "string"
          },
          "transit": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatorySiteBriefWorkflowResponse": {
        "properties": {
          "applied_filters": {
            "$ref": "#/components/schemas/RegulatorySiteBriefAppliedFilters"
          },
          "caveats": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "environment_alerts": {
            "items": {
              "$ref": "#/components/schemas/EnvironmentAlert"
            },
            "type": "array"
          },
          "facility": {
            "$ref": "#/components/schemas/RegulatoryFacility"
          },
          "family_notices": {
            "$ref": "#/components/schemas/RegulatorySiteBriefFamilyNotices"
          },
          "inspections": {
            "items": {
              "$ref": "#/components/schemas/RegulatoryInspectionRecord"
            },
            "type": "array"
          },
          "licenses": {
            "items": {
              "$ref": "#/components/schemas/RegulatoryLicenseRecord"
            },
            "type": "array"
          },
          "permits": {
            "items": {
              "$ref": "#/components/schemas/RegulatoryPermitRecord"
            },
            "type": "array"
          },
          "transit_routes": {
            "items": {
              "$ref": "#/components/schemas/TransitRoute"
            },
            "type": "array"
          },
          "workflow": {
            "type": "string"
          },
          "workflow_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryWatchRequest": {
        "properties": {
          "cadence_hours": {
            "type": "integer"
          },
          "delivery_channel": {
            "type": "string"
          },
          "facility_id": {
            "type": "string"
          },
          "query": {
            "type": "string"
          },
          "record_id": {
            "type": "string"
          },
          "record_type": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RegulatoryWatchResponse": {
        "properties": {
          "bootstrap_limitations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "cadence_hours": {
            "type": "integer"
          },
          "delivery_channel": {
            "type": "string"
          },
          "freshness_description": {
            "type": "string"
          },
          "legal_notice": {
            "type": "string"
          },
          "observed_filter": {
            "$ref": "#/components/schemas/RegulatoryWatchRequest"
          },
          "product_code": {
            "type": "string"
          },
          "recommended_next_steps": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scope_summary": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          },
          "watch_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RoleTemplate": {
        "properties": {
          "assignable_by": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "default_scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": {
            "type": "string"
          },
          "membership_role": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "template_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RotatedAPIKey": {
        "properties": {
          "api_key_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "previous_api_key_id": {
            "type": "string"
          },
          "raw_key": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SAMLConfiguration": {
        "properties": {
          "acs_url": {
            "type": "string"
          },
          "entity_id": {
            "type": "string"
          },
          "last_validated_at": {
            "type": "string"
          },
          "sign_in_url": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "x509_cert_sha256": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SCIMConfiguration": {
        "properties": {
          "endpoint_url": {
            "type": "string"
          },
          "last_validated_at": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "token_hint": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ScopedKeyPreset": {
        "properties": {
          "default_rotation_days": {
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "key_type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "preset_id": {
            "type": "string"
          },
          "recommended_environment": {
            "type": "string"
          },
          "recommended_role": {
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ServiceAccountProfile": {
        "properties": {
          "last_rotated_at": {
            "type": "string"
          },
          "lifecycle_state": {
            "type": "string"
          },
          "next_rotation_due_at": {
            "type": "string"
          },
          "owner_user_id": {
            "type": "string"
          },
          "rotation_interval_days": {
            "type": "integer"
          },
          "service_account_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SpendSummary": {
        "properties": {
          "assumptions": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "currency": {
            "type": "string"
          },
          "estimated_end_of_period_spend": {
            "type": "number"
          },
          "estimated_end_of_period_spend_usd": {
            "type": "number"
          },
          "estimated_spend_to_date": {
            "type": "number"
          },
          "estimated_spend_to_date_usd": {
            "type": "number"
          },
          "period_end": {
            "type": "string"
          },
          "period_progress_percent": {
            "type": "integer"
          },
          "period_start": {
            "type": "string"
          },
          "plan_cost_period": {
            "type": "number"
          },
          "plan_cost_period_usd": {
            "type": "number"
          },
          "spend_model": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Subscription": {
        "properties": {
          "automatic_tax": {
            "type": "boolean"
          },
          "billing_country": {
            "type": "string"
          },
          "billing_customer_id": {
            "type": "string"
          },
          "billing_provider": {
            "type": "string"
          },
          "billing_status": {
            "type": "string"
          },
          "cancel_at": {
            "type": "string"
          },
          "coupon_code": {
            "type": "string"
          },
          "coupon_percent_off": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "current_period_end": {
            "type": "string"
          },
          "current_period_start": {
            "type": "string"
          },
          "dunning_state": {
            "type": "string"
          },
          "entitlement_state": {
            "type": "string"
          },
          "grace_period_ends_at": {
            "type": "string"
          },
          "last_invoice_amount_due": {
            "type": "integer"
          },
          "last_invoice_amount_paid": {
            "type": "integer"
          },
          "last_invoice_discount": {
            "type": "integer"
          },
          "last_invoice_id": {
            "type": "string"
          },
          "last_invoice_issued_at": {
            "type": "string"
          },
          "last_invoice_status": {
            "type": "string"
          },
          "last_invoice_subtotal": {
            "type": "integer"
          },
          "last_invoice_tax": {
            "type": "integer"
          },
          "next_invoice_at": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "overage_alert_threshold_percent": {
            "type": "integer"
          },
          "overage_cap_requests": {
            "type": "integer"
          },
          "overage_mode": {
            "type": "string"
          },
          "overage_rate_per_1000_requests": {
            "type": "integer"
          },
          "plan_code": {
            "type": "string"
          },
          "subscription_id": {
            "type": "string"
          },
          "tax_exempt": {
            "type": "string"
          },
          "trial_ends_at": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SupportBundle": {
        "properties": {
          "bundle_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "intentionally_omitted": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "organization_id": {
            "type": "string"
          },
          "recent_failures": {
            "items": {
              "$ref": "#/components/schemas/SupportFailure"
            },
            "type": "array"
          },
          "redaction_policy": {
            "type": "string"
          },
          "request_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "safe_diagnostics": {
            "type": "object"
          },
          "ticket_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SupportFailure": {
        "properties": {
          "api_key_id": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "occurred_at": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "response_status": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "SupportTicket": {
        "properties": {
          "assigned_operator_id": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "lane": {
            "type": "string"
          },
          "legal_review_posture": {
            "type": "string"
          },
          "lifecycle_state": {
            "type": "string"
          },
          "module": {
            "type": "string"
          },
          "operator_queue": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "priority": {
            "type": "string"
          },
          "record_id": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "request_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "safety_redaction_policy": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "ticket_id": {
            "type": "string"
          },
          "triage_summary": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TransitAppliedFilters": {
        "properties": {
          "limit": {
            "type": "integer"
          },
          "query": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TransitListResponse": {
        "properties": {
          "applied_filters": {
            "$ref": "#/components/schemas/TransitAppliedFilters"
          },
          "count": {
            "type": "integer"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/TransitRoute"
            },
            "type": "array"
          },
          "legal_notice": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TransitRoute": {
        "properties": {
          "agency_name": {
            "type": "string"
          },
          "attribution_text": {
            "type": "string"
          },
          "authoritative_language": {
            "type": "string"
          },
          "last_verified_at": {
            "type": "string"
          },
          "legal_review_status": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "region_id": {
            "type": "string"
          },
          "route_code": {
            "type": "string"
          },
          "route_id": {
            "type": "string"
          },
          "route_long_name": {
            "type": "string"
          },
          "route_short_name": {
            "type": "string"
          },
          "service_area": {
            "type": "string"
          },
          "source_dataset_id": {
            "type": "string"
          },
          "source_feed_format": {
            "type": "string"
          },
          "source_publisher": {
            "type": "string"
          },
          "source_record_url": {
            "type": "string"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "UpdateSubscriptionBillingControlsRequest": {
        "properties": {
          "automatic_tax": {
            "type": "boolean"
          },
          "billing_country": {
            "type": "string"
          },
          "coupon_code": {
            "type": "string"
          },
          "coupon_percent_off": {
            "type": "integer"
          },
          "overage_alert_threshold_percent": {
            "type": "integer"
          },
          "overage_cap_requests": {
            "type": "integer"
          },
          "overage_mode": {
            "type": "string"
          },
          "overage_rate_per_1000_requests": {
            "type": "integer"
          },
          "tax_exempt": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "UsageAlert": {
        "properties": {
          "api_key_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "product_code": {
            "type": "string"
          },
          "projected_overrun": {
            "type": "boolean"
          },
          "severity": {
            "type": "string"
          },
          "usage_percent": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "UsageBreakdown": {
        "properties": {
          "project_breakdown": {
            "items": {
              "$ref": "#/components/schemas/EnvironmentUsageShare"
            },
            "type": "array"
          },
          "top_keys": {
            "items": {
              "$ref": "#/components/schemas/KeyUsageShare"
            },
            "type": "array"
          },
          "top_products": {
            "items": {
              "$ref": "#/components/schemas/ProductUsageShare"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "UsageSummary": {
        "properties": {
          "alerts": {
            "items": {
              "$ref": "#/components/schemas/UsageAlert"
            },
            "type": "array"
          },
          "environments": {
            "items": {
              "$ref": "#/components/schemas/EnvironmentUsage"
            },
            "type": "array"
          },
          "generated_at": {
            "type": "string"
          },
          "key_usage": {
            "items": {
              "$ref": "#/components/schemas/KeyUsage"
            },
            "type": "array"
          },
          "organization_id": {
            "type": "string"
          },
          "plan_code": {
            "type": "string"
          },
          "products": {
            "items": {
              "properties": {
                "period_end": {
                  "type": "string"
                },
                "period_start": {
                  "type": "string"
                },
                "product_code": {
                  "type": "string"
                },
                "quota_limit": {
                  "type": "integer"
                },
                "quota_remaining": {
                  "type": "integer"
                },
                "request_count": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "Watch": {
        "properties": {
          "bootstrap_limitations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "cadence_hours": {
            "type": "integer"
          },
          "created_at": {
            "type": "string"
          },
          "delivery_channel": {
            "type": "string"
          },
          "freshness_description": {
            "type": "string"
          },
          "last_evaluated_at": {
            "type": "string"
          },
          "observed_filter": {
            "type": "object"
          },
          "organization_id": {
            "type": "string"
          },
          "product_code": {
            "type": "string"
          },
          "recommended_next_steps": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scope_summary": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "watch_id": {
            "type": "string"
          },
          "watch_type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "WatchCreateRequest": {
        "properties": {
          "cadence_hours": {
            "type": "integer"
          },
          "delivery_channel": {
            "type": "string"
          },
          "freshness_description": {
            "type": "string"
          },
          "observed_filter": {
            "type": "object"
          },
          "product_code": {
            "type": "string"
          },
          "scope_summary": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          },
          "watch_type": {
            "type": "string"
          }
        },
        "required": [
          "product_code",
          "watch_type"
        ],
        "type": "object"
      },
      "WatchUpdateRequest": {
        "properties": {
          "cadence_hours": {
            "type": "integer"
          },
          "delivery_channel": {
            "type": "string"
          },
          "scope_summary": {
            "type": "string"
          },
          "trigger": {
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "SmartAPIs exposes legally reviewed open-data APIs for developers and LLM agents.\nThe public surface is designed to be human-readable, machine-readable, and agent-readable.\n",
    "summary": "Agent-ready real-world APIs for places, products, regulatory, transit, environment, and civic workflows.",
    "title": "SmartAPIs.net",
    "version": "0.2.0",
    "x-smartapis-deprecation-policy": {
      "communication_channels": [
        "/status",
        "/v1/openapi.yaml",
        "/v1/openapi.json",
        "public docs",
        "support responses"
      ],
      "exception_policy": "Security or legal emergencies may require faster mitigations than the standard notice window.",
      "minimum_notice_days": 90
    },
    "x-smartapis-versioning-policy": {
      "compatibility_model": "additive_within_major",
      "current_major_version": "v1",
      "guidance": "Breaking changes should ship with explicit migration guidance instead of silent contract drift.",
      "public_contract_scope": [
        "/v1/openapi.yaml",
        "/v1/openapi.json",
        "/v1/attribution",
        "/v1/agent/capabilities",
        "/mcp"
      ]
    }
  },
  "openapi": "3.1.0",
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service is healthy"
          }
        },
        "summary": "Health check",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/readyz": {
      "get": {
        "operationId": "getReadiness",
        "responses": {
          "200": {
            "description": "Service is ready"
          }
        },
        "summary": "Readiness check",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/agent/capabilities": {
      "get": {
        "operationId": "getAgentCapabilities",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "default": {
                    "value": {
                      "auth_methods": [
                        "api_key"
                      ],
                      "capability_version": "v2",
                      "discovery_endpoints": [
                        {
                          "auth": "public",
                          "description": "Discovery metadata for developers and agents.",
                          "method": "GET",
                          "path": "/v1/agent/capabilities"
                        }
                      ],
                      "domains": [
                        "places",
                        "products",
                        "regulatory",
                        "transit",
                        "environment",
                        "civic"
                      ],
                      "example_recipes": [
                        {
                          "description": "Discover capabilities, inspect context, and query places.",
                          "languages": [
                            "curl",
                            "python",
                            "javascript"
                          ],
                          "slug": "restaurant-finder",
                          "title": "Build a Restaurant Finder Agent in 5 Minutes"
                        }
                      ],
                      "family_capabilities": [
                        {
                          "description": "Search and interpret legally reviewed place records.",
                          "example_recipe": "restaurant-finder-agent",
                          "family": "places",
                          "mcp_detail_tool": "smartagent_place_agent_context_get",
                          "mcp_search_tool": "smartagent_places_search",
                          "required_scopes": [
                            "places:read"
                          ],
                          "rest_base_path": "/v1/places"
                        },
                        {
                          "description": "Search product references plus offer and price-history snapshots.",
                          "example_recipe": "products-watch-routes",
                          "family": "products",
                          "mcp_search_tool": "smartagent_products_search",
                          "required_scopes": [
                            "products:read"
                          ],
                          "rest_base_path": "/v1/products"
                        }
                      ],
                      "legal_posture": "Public responses prioritize official provenance, attribution, and legal review status.",
                      "mcp_tooling": {
                        "authenticated_tip": "Provide X-API-Key or Authorization Bearer for product and management tools; discovery tools are public.",
                        "discovery_tools": [
                          "smartagent_discovery_capabilities",
                          "smartagent_catalog_list_plans",
                          "smartagent_context_get"
                        ],
                        "endpoint_url": "/mcp",
                        "protocol_version": "2025-03-26"
                      },
                      "planned_domains": [
                        "compliance",
                        "places-v2"
                      ],
                      "positioning": "Real-world intelligence for AI agents, built on legally reviewed public data and exposed through machine-readable, coverage-visible APIs.",
                      "protocols": [
                        "rest",
                        "openapi",
                        "mcp"
                      ],
                      "service": "SmartAPIs.net",
                      "supported_queries": [
                        "find_restaurants",
                        "find_products",
                        "find_regulatory_records",
                        "plan_transit",
                        "environment_conditions",
                        "civic_service_lookup"
                      ],
                      "tagline": "Legally reviewed, machine-readable, coverage-visible real-world intelligence."
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/CapabilitiesResponse"
                }
              }
            },
            "description": "Agent capability document"
          }
        },
        "summary": "Get the public agent capability document",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/agent/context/{location_id}": {
      "get": {
        "operationId": "getAgentContext",
        "parameters": [
          {
            "in": "path",
            "name": "location_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "montreal": {
                    "value": {
                      "agent_summary": "Strong launch metro for restaurant discovery, transit routing, and civic assistance.",
                      "air_quality": "moderate",
                      "anchor_city": "Montreal",
                      "business_density": "high",
                      "country_code": "CA",
                      "display_name": "Greater Montreal",
                      "legal_notice": "Agent summaries are SmartAPIs interpretations layered on top of reviewed source data.",
                      "location_id": "montreal",
                      "population": {
                        "band": "4m_to_5m",
                        "notes": "Large bilingual metro with dense neighborhoods."
                      },
                      "recommended_queries": [
                        "find_restaurants",
                        "plan_transit",
                        "environment_conditions"
                      ],
                      "recommended_use_cases": [
                        "restaurant finder agent",
                        "city assistant",
                        "transit planning assistant"
                      ],
                      "region_id": "greater-montreal",
                      "source_dataset_ids": [
                        "ca_qc_mtl_places",
                        "ca_qc_mtl_transit"
                      ],
                      "summary_status": "advisory",
                      "supported_modules": [
                        "places",
                        "transit",
                        "environment",
                        "civic"
                      ],
                      "timezone": "America/Toronto",
                      "transit_systems": [
                        "STM",
                        "EXO",
                        "REM"
                      ],
                      "weather_profile": "four-season continental climate"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ContextResponse"
                }
              }
            },
            "description": "Agent context record"
          },
          "404": {
            "description": "Context not found"
          }
        },
        "summary": "Get structured context for a supported location",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/agent/query": {
      "post": {
        "operationId": "agentQueryPlan",
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "restaurant_intent": {
                  "value": {
                    "available_scopes": [
                      "places:read"
                    ],
                    "location_id": "new-york-city",
                    "preferred_protocol": "rest",
                    "query": "find restaurant options near downtown"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/AgentQueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentQueryResponse"
                }
              }
            },
            "description": "Deterministic planner recommendation and constraints"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Query payload invalid"
          }
        },
        "summary": "Deterministically recommend the best SmartAPIs route family for an agent query",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/attribution": {
      "get": {
        "description": "Returns the public attribution catalog for reviewed SmartAPIs source families. Filters are\nadditive and intended for provenance and contract review, not internal diagnostics.\n",
        "operationId": "listAttributionRecords",
        "parameters": [
          {
            "description": "Limit results to one module family such as places, products, or regulatory.",
            "in": "query",
            "name": "module",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Limit results to one launch region when attribution is region-specific.",
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Case-insensitive substring match against the published attribution source name.",
            "in": "query",
            "name": "publisher_name",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/AttributionRecord"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Attribution catalog"
          }
        },
        "summary": "List attribution records",
        "tags": [
          "Legal"
        ]
      }
    },
    "/v1/billing/plans": {
      "get": {
        "description": "Returns the public SmartAPIs pricing surface, including the free developer tier,\ncheckout eligibility, monthly versus annual billing options, supported currencies,\nand the currently visible launch regions.\nThis endpoint is intentionally public so developers and agents can evaluate fit before purchase.\n",
        "operationId": "listBillingPlans",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "default": {
                    "value": [
                      {
                        "billing_interval": "month",
                        "checkout_enabled": false,
                        "currencies": [
                          {
                            "currency": "usd",
                            "monthly_quota": 500,
                            "unit_amount": 0
                          }
                        ],
                        "description": "Free developer access for evaluation and lightweight agent prototyping.",
                        "display_name": "SmartAPIs.net Developer Free",
                        "included_products": [
                          "places",
                          "transit",
                          "environment",
                          "civic"
                        ],
                        "launch_region_ids": [
                          "gta",
                          "greater-montreal",
                          "metro-vancouver",
                          "calgary-region",
                          "edmonton-region",
                          "ottawa-region",
                          "seattle-metro",
                          "chicago-metro",
                          "new-york-city",
                          "san-francisco-bay",
                          "austin-metro",
                          "los-angeles-metro"
                        ],
                        "plan_code": "developer-free"
                      },
                      {
                        "billing_interval": "month",
                        "checkout_enabled": true,
                        "currencies": [
                          {
                            "currency": "usd",
                            "monthly_quota": 10000,
                            "unit_amount": 9500
                          }
                        ],
                        "description": "Full monthly access to all SmartAPIs.net API families.",
                        "display_name": "SmartAPIs.net All Access Monthly",
                        "included_products": [
                          "places",
                          "products",
                          "regulatory",
                          "transit",
                          "environment",
                          "civic"
                        ],
                        "launch_region_ids": [
                          "gta",
                          "greater-montreal",
                          "metro-vancouver",
                          "calgary-region",
                          "edmonton-region",
                          "ottawa-region",
                          "seattle-metro",
                          "chicago-metro",
                          "new-york-city",
                          "san-francisco-bay",
                          "austin-metro",
                          "los-angeles-metro"
                        ],
                        "plan_code": "all-access-monthly"
                      },
                      {
                        "billing_interval": "year",
                        "checkout_enabled": true,
                        "currencies": [
                          {
                            "currency": "usd",
                            "monthly_quota": 10000,
                            "unit_amount": 95000
                          }
                        ],
                        "description": "Yearly access to all SmartAPIs.net API families with two months off.",
                        "display_name": "SmartAPIs.net All Access Annual",
                        "included_products": [
                          "places",
                          "products",
                          "regulatory",
                          "transit",
                          "environment",
                          "civic"
                        ],
                        "launch_region_ids": [
                          "gta",
                          "greater-montreal",
                          "metro-vancouver",
                          "calgary-region",
                          "edmonton-region",
                          "ottawa-region",
                          "seattle-metro",
                          "chicago-metro",
                          "new-york-city",
                          "san-francisco-bay",
                          "austin-metro",
                          "los-angeles-metro"
                        ],
                        "plan_code": "all-access-annual"
                      }
                    ]
                  }
                },
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CatalogEntry"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Published plan catalog"
          }
        },
        "summary": "List the public plan catalog",
        "tags": [
          "Billing"
        ]
      }
    },
    "/v1/billing/stripe/checkout-session": {
      "post": {
        "description": "Creates a Stripe-hosted checkout session for a paid SmartAPIs plan.\nThe free developer tier is intentionally excluded from checkout because it is an\nactivation path, not a paid subscription product.\nCheckpoint 5 adds additive support for localized billing hints, automatic tax, coupon codes,\ntrial periods, and overage posture metadata that SmartAPIs can use for customer guidance and lifecycle visibility.\n",
        "operationId": "createStripeCheckoutSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckoutRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "default": {
                    "value": {
                      "id": "cs_test_123",
                      "mode": "subscription",
                      "status": "open",
                      "url": "https://checkout.stripe.com/c/pay/cs_test_123"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/CheckoutSessionResponse"
                }
              }
            },
            "description": "Checkout session created"
          },
          "400": {
            "description": "Invalid request or unsupported plan"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "502": {
            "description": "Stripe request failed upstream"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Create a Stripe Checkout Session",
        "tags": [
          "Billing"
        ]
      }
    },
    "/v1/billing/stripe/portal-session": {
      "post": {
        "description": "Creates a hosted Stripe billing-management session for the current subscription.\nSmartAPIs uses Stripe for billing changes, invoices, payment methods, and cancellation flows.\n",
        "operationId": "createStripePortalSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "return_url": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "default": {
                    "value": {
                      "id": "bps_123",
                      "url": "https://billing.stripe.com/p/session/test_123"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/PortalSessionResponse"
                }
              }
            },
            "description": "Billing portal session created"
          },
          "400": {
            "description": "Invalid request or no linked Stripe customer"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "502": {
            "description": "Stripe request failed upstream"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Create a Stripe Customer Portal session",
        "tags": [
          "Billing"
        ]
      }
    },
    "/v1/billing/stripe/webhook": {
      "post": {
        "operationId": "receiveStripeWebhook",
        "responses": {
          "200": {
            "description": "Webhook accepted"
          },
          "400": {
            "description": "Invalid webhook payload or signature"
          }
        },
        "summary": "Receive Stripe webhook events",
        "tags": [
          "Billing"
        ]
      }
    },
    "/v1/civic/service-points": {
      "get": {
        "operationId": "listCivicServicePoints",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "permits": {
                    "value": {
                      "applied_filters": {
                        "limit": 5,
                        "query": "licence",
                        "region_id": "gta"
                      },
                      "count": 1,
                      "items": [
                        {
                          "address_line_1": "850 Coxwell Ave",
                          "attribution_text": "City of Toronto Open Data.",
                          "authoritative_language": "en",
                          "department_name": "Municipal Licensing and Standards",
                          "last_verified_at": "2026-03-15T00:00:00Z",
                          "legal_review_status": "approved_for_mvp",
                          "license_url": "https://example.org/license",
                          "municipality": "Toronto",
                          "phone": 311,
                          "postal_code": "M4C5R1",
                          "privacy_review_status": "approved_for_mvp",
                          "region_id": "gta",
                          "service_category": "licensing",
                          "service_name_en": "Business Licence Counter",
                          "service_point_id": "civic_tor_001",
                          "source_dataset_id": "ca_on_tor_civic_001",
                          "source_publisher": "City of Toronto",
                          "source_record_url": "https://example.org/service-points/1",
                          "tags": [
                            "business",
                            "licensing"
                          ],
                          "website_url": "https://www.toronto.ca"
                        }
                      ],
                      "legal_notice": "Bootstrap civic results are limited to publicly listed service points with preserved attribution and privacy-reviewed contact fields only."
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/CivicServicePointListResponse"
                }
              }
            },
            "description": "Civic service point list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List legally reviewed civic service points",
        "tags": [
          "Civic"
        ]
      }
    },
    "/v1/civic/service-points/{service_point_id}": {
      "get": {
        "operationId": "getCivicServicePoint",
        "parameters": [
          {
            "in": "path",
            "name": "service_point_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CivicServicePoint"
                }
              }
            },
            "description": "Civic service point record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Service point not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed civic service point",
        "tags": [
          "Civic"
        ]
      }
    },
    "/v1/coverage/regions": {
      "get": {
        "description": "Returns the public launch coverage map for SmartAPIs across currently supported\nNorth American metros. Customers and agents should call this before purchase or\nbefore attempting to build region-specific workflows.\n",
        "operationId": "listCoverageRegions",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "default": {
                    "value": [
                      {
                        "anchor_municipalities": [
                          "Toronto"
                        ],
                        "country_code": "CA",
                        "coverage": {
                          "civic": "planned",
                          "environment": "planned",
                          "places": "planned",
                          "transit": "planned"
                        },
                        "display_name_en": "Greater Toronto Area",
                        "display_name_fr": "Grand Toronto",
                        "geography_type": "metro_region",
                        "region_id": "gta",
                        "timezone": "America/Toronto"
                      },
                      {
                        "anchor_municipalities": [
                          "New York City"
                        ],
                        "country_code": "US",
                        "coverage": {
                          "civic": "planned",
                          "environment": "planned",
                          "places": "planned",
                          "transit": "planned"
                        },
                        "display_name_en": "New York City",
                        "display_name_fr": "New York",
                        "geography_type": "metro_region",
                        "region_id": "new-york-city",
                        "timezone": "America/New_York"
                      }
                    ]
                  }
                },
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CoverageRegion"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Coverage region list"
          }
        },
        "summary": "List launch coverage regions",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/coverage/regions/{region_id}": {
      "get": {
        "description": "Returns one public region record, including geography metadata, timezone,\nand module coverage posture for that metro.\n",
        "operationId": "getCoverageRegion",
        "parameters": [
          {
            "in": "path",
            "name": "region_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoverageRegion"
                }
              }
            },
            "description": "Coverage region"
          },
          "404": {
            "description": "Region not found"
          }
        },
        "summary": "Get one launch coverage region",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/dashboard": {
      "get": {
        "description": "Returns the combined dashboard payload for the current organization, including\norganization details, subscription state, entitlements, key summaries, usage, audit history,\nand whether billing portal access is currently available.\n",
        "operationId": "getDashboardSummary",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "default": {
                    "value": {
                      "api_keys": [
                        {
                          "api_key_id": "key_001",
                          "label": "bootstrap-admin",
                          "prefix": "sapi_test_bootstrap",
                          "role": "admin",
                          "scopes": [
                            "org:read",
                            "api_keys:write",
                            "billing:write",
                            "usage:read",
                            "audit:read"
                          ],
                          "status": "active"
                        }
                      ],
                      "audit_events": [
                        {
                          "actor_id": "stripe",
                          "actor_type": "system",
                          "audit_event_id": "audit_001",
                          "created_at": "2026-03-15T00:00:00Z",
                          "event_payload": {},
                          "event_type": "billing.subscription.synced",
                          "organization_id": "org_demo_001"
                        }
                      ],
                      "billing_lifecycle": {
                        "access_state": "active",
                        "current_period_end": "2027-03-01T00:00:00Z",
                        "dunning_state": "healthy",
                        "entitlement_state": "active",
                        "grace_period_ends_at": "2026-03-28T00:00:00Z",
                        "latest_invoice_status": "paid",
                        "manage_billing_message": "Stripe portal is ready for this subscription.",
                        "next_invoice_at": "2027-03-01T00:00:00Z",
                        "trial_ends_at": "2026-03-21T00:00:00Z"
                      },
                      "commercial_analytics": {
                        "data_limitations": [
                          "Spend and overage values remain advisory until Stripe invoice truth is synced."
                        ],
                        "recommendations": [
                          {
                            "action_hint": "Confirm billing country and tax posture before renewal.",
                            "action_label": "Review billing controls",
                            "detail": "Automatic tax is already active for this subscription.",
                            "priority": "medium",
                            "title": "Keep automated tax enabled",
                            "why_now": "This keeps invoice totals aligned when billing country changes."
                          }
                        ],
                        "spend": {
                          "assumptions": [
                            "Overage estimates remain advisory until Stripe invoice truth is available."
                          ],
                          "currency": "usd",
                          "estimated_end_of_period_spend": 950,
                          "estimated_end_of_period_spend_usd": 950,
                          "estimated_spend_to_date": 950,
                          "estimated_spend_to_date_usd": 950,
                          "period_end": "2027-03-01T00:00:00Z",
                          "period_progress_percent": 4,
                          "period_start": "2026-03-01T00:00:00Z",
                          "plan_cost_period": 950,
                          "plan_cost_period_usd": 950,
                          "spend_model": "plan_price_plus_configured_overage_projection"
                        },
                        "usage_breakdown": {
                          "project_breakdown": [],
                          "top_keys": [
                            {
                              "api_key_id": "key_001",
                              "key_type": "client",
                              "label": "bootstrap-admin",
                              "request_count": 12,
                              "share_percent": 100,
                              "usage_percent": 1
                            }
                          ],
                          "top_products": [
                            {
                              "product_code": "places",
                              "request_count": 12,
                              "share_percent": 100
                            }
                          ]
                        }
                      },
                      "entitlements": [
                        {
                          "entitlement_id": "ent_001",
                          "feature_code": "access",
                          "product_code": "places",
                          "status": "active"
                        }
                      ],
                      "invoices": [
                        {
                          "amount_due": 83600,
                          "amount_paid": 83600,
                          "currency": "usd",
                          "description": "Latest hosted billing invoice or invoice-equivalent summary.",
                          "discount_amount": 23750,
                          "due_at": "2027-03-01T00:00:00Z",
                          "invoice_id": "in_123",
                          "issued_at": "2026-03-01T00:00:00Z",
                          "period_end": "2027-03-01T00:00:00Z",
                          "period_start": "2026-03-01T00:00:00Z",
                          "source_of_truth": "stripe_invoice",
                          "status": "paid",
                          "subscription_id": "sub_demo_001",
                          "subtotal": 95000,
                          "tax_amount": 12350
                        }
                      ],
                      "manage_billing_ok": true,
                      "organization": {
                        "billing_email": "smartagentapis@gmail.com",
                        "default_currency": "USD",
                        "default_locale": "en-US",
                        "display_name": "SmartAPIs Demo Org",
                        "legal_name": "Nouneh, Roy",
                        "organization_id": "org_demo_001",
                        "slug": "smartapis-demo",
                        "status": "active"
                      },
                      "overage": {
                        "alert_threshold_percent": 85,
                        "alert_triggered": false,
                        "cap_requests": 15000,
                        "currency": "usd",
                        "enforced": false,
                        "estimated_amount": 0,
                        "included_requests": 60000,
                        "mode": "capped",
                        "observed_requests": 12,
                        "overage_requests": 0,
                        "rate_per_1000_requests": 2900,
                        "remaining_before_cap": 14988
                      },
                      "plan_catalog": [
                        {
                          "display_name": "SmartAPIs.net All Access Annual",
                          "plan_code": "all-access-annual"
                        }
                      ],
                      "subscription": {
                        "automatic_tax": true,
                        "billing_country": "CA",
                        "billing_customer_id": "cus_123",
                        "billing_provider": "stripe",
                        "billing_status": "active",
                        "coupon_code": "LAUNCH25",
                        "coupon_percent_off": 25,
                        "currency": "usd",
                        "current_period_end": "2027-03-01T00:00:00Z",
                        "current_period_start": "2026-03-01T00:00:00Z",
                        "dunning_state": "healthy",
                        "entitlement_state": "active",
                        "grace_period_ends_at": "2026-03-28T00:00:00Z",
                        "last_invoice_amount_due": 83600,
                        "last_invoice_amount_paid": 83600,
                        "last_invoice_discount": 23750,
                        "last_invoice_id": "in_123",
                        "last_invoice_issued_at": "2026-03-01T00:00:00Z",
                        "last_invoice_status": "paid",
                        "last_invoice_subtotal": 95000,
                        "last_invoice_tax": 12350,
                        "next_invoice_at": "2027-03-01T00:00:00Z",
                        "organization_id": "org_demo_001",
                        "overage_alert_threshold_percent": 85,
                        "overage_cap_requests": 15000,
                        "overage_mode": "capped",
                        "overage_rate_per_1000_requests": 2900,
                        "plan_code": "all-access-annual",
                        "subscription_id": "sub_demo_001",
                        "tax_exempt": "none",
                        "trial_ends_at": "2026-03-21T00:00:00Z"
                      },
                      "usage": {
                        "alerts": [],
                        "generated_at": "2026-03-15T00:00:00Z",
                        "key_usage": [
                          {
                            "alert_threshold_percent": 80,
                            "alert_triggered": false,
                            "api_key_id": "key_001",
                            "enforcement_mode": "advisory",
                            "key_type": "client",
                            "label": "bootstrap-admin",
                            "quota_limit": 10000,
                            "quota_remaining": 9988,
                            "request_count": 12,
                            "role": "admin",
                            "status": "active",
                            "usage_percent": 1
                          }
                        ],
                        "organization_id": "org_demo_001",
                        "plan_code": "all-access-annual",
                        "products": [
                          {
                            "period_end": "2026-04-01T00:00:00Z",
                            "period_start": "2026-03-01T00:00:00Z",
                            "product_code": "places",
                            "quota_limit": 10000,
                            "quota_remaining": 9988,
                            "request_count": 12
                          }
                        ]
                      }
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/DashboardSummary"
                }
              }
            },
            "description": "Dashboard summary"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get the lightweight dashboard summary",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/environment/alerts": {
      "get": {
        "operationId": "listEnvironmentAlerts",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "smoke": {
                    "value": {
                      "applied_filters": {
                        "limit": 5,
                        "query": "smoke",
                        "region_id": "metro-vancouver"
                      },
                      "count": 1,
                      "items": [
                        {
                          "alert_id": "alert_van_001",
                          "alert_type": "air_quality_statement",
                          "attribution_text": "Environment and Climate Change Canada.",
                          "authoritative_language": "en",
                          "headline_en": "Air quality statement in effect.",
                          "last_verified_at": "2026-03-15T00:00:00Z",
                          "legal_review_status": "approved_for_mvp",
                          "license_url": "https://example.org/license",
                          "operational_status": "active",
                          "publisher_name": "Environment and Climate Change Canada",
                          "region_id": "metro-vancouver",
                          "severity": "moderate",
                          "source_dataset_id": "ca_bc_environment_alerts_001",
                          "source_publisher": "ECCC",
                          "source_record_url": "https://example.org/alerts/1",
                          "summary_en": "Smoke from regional wildfire activity may affect sensitive groups.",
                          "tags": [
                            "air-quality",
                            "smoke"
                          ],
                          "valid_from": "2026-03-14T13:00:00Z",
                          "valid_until": "2026-03-16T04:00:00Z"
                        }
                      ],
                      "legal_notice": "Bootstrap environment results are limited to legally reviewed public alert references with preserved source attribution and no safety-critical transformations."
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/EnvironmentAlertListResponse"
                }
              }
            },
            "description": "Environment alert list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List legally reviewed environment alerts",
        "tags": [
          "Environment"
        ]
      }
    },
    "/v1/environment/alerts/{alert_id}": {
      "get": {
        "operationId": "getEnvironmentAlert",
        "parameters": [
          {
            "in": "path",
            "name": "alert_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnvironmentAlert"
                }
              }
            },
            "description": "Environment alert record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Alert not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed environment alert",
        "tags": [
          "Environment"
        ]
      }
    },
    "/v1/legal/datasets": {
      "get": {
        "operationId": "listLegalDatasets",
        "parameters": [
          {
            "in": "query",
            "name": "module",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Approved dataset registry"
          }
        },
        "summary": "List approved dataset sources",
        "tags": [
          "Legal"
        ]
      }
    },
    "/v1/legal/datasets/{dataset_id}": {
      "get": {
        "operationId": "getLegalDataset",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Dataset source record"
          },
          "404": {
            "description": "Dataset not found"
          }
        },
        "summary": "Get one approved dataset source",
        "tags": [
          "Legal"
        ]
      }
    },
    "/v1/openapi.json": {
      "get": {
        "description": "Use this route when you want a machine-consumable API contract for code generation,\nagent planning, or quick schema inspection.\n",
        "operationId": "getOpenAPIJSON",
        "responses": {
          "200": {
            "description": "OpenAPI JSON document"
          }
        },
        "summary": "Get the OpenAPI document in JSON format",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/openapi.yaml": {
      "get": {
        "description": "This discovery surface is treated as public-contract critical. Use it when humans or tooling\nneed the canonical YAML representation of the SmartAPIs public contract.\n",
        "operationId": "getOpenAPIYAML",
        "responses": {
          "200": {
            "description": "OpenAPI YAML document"
          }
        },
        "summary": "Get the OpenAPI document in YAML format",
        "tags": [
          "Discovery"
        ]
      }
    },
    "/v1/ops/dataset-families": {
      "get": {
        "operationId": "getOpsDatasetFamilies",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpsDatasetFamiliesResponse"
                }
              }
            },
            "description": "Dataset-family operational compliance state"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get dataset-family kill switches and legal review states",
        "tags": [
          "Operations"
        ]
      }
    },
    "/v1/ops/failures": {
      "get": {
        "operationId": "getOpsFailures",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpsFailureResponse"
                }
              }
            },
            "description": "Auth and billing failure snapshot"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get auth and billing failure visibility",
        "tags": [
          "Operations"
        ]
      }
    },
    "/v1/ops/route-families": {
      "get": {
        "operationId": "getOpsRouteFamilies",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpsRouteFamilyResponse"
                }
              }
            },
            "description": "Route-family request visibility snapshot"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get route-family request visibility",
        "tags": [
          "Operations"
        ]
      }
    },
    "/v1/organizations/me": {
      "get": {
        "operationId": "getCurrentOrganization",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            },
            "description": "Organization record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get the current organization",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/api-keys": {
      "get": {
        "operationId": "listCurrentOrganizationAPIKeys",
        "responses": {
          "200": {
            "description": "API key summaries"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List current organization API key summaries",
        "tags": [
          "Control Plane"
        ]
      },
      "post": {
        "description": "Creates a new client key for product access. The raw key is only returned once,\nso clients should store it securely immediately after creation.\n",
        "operationId": "createCurrentOrganizationAPIKey",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAPIKeyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "examples": {
                  "default": {
                    "value": {
                      "api_key_id": "key_abc123",
                      "created_at": "2026-03-15T00:00:00Z",
                      "label": "first-client-key",
                      "prefix": "sapi_live_abc12345",
                      "raw_key": "sapi_live_abc12345_xxxxxxxxxxxxxxxxx",
                      "role": "client",
                      "scopes": [
                        "places:read",
                        "transit:read"
                      ],
                      "status": "active"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/IssuedAPIKey"
                }
              }
            },
            "description": "API key issued"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Issue a new client API key",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/api-keys/{api_key_id}": {
      "delete": {
        "operationId": "revokeCurrentOrganizationAPIKey",
        "parameters": [
          {
            "in": "path",
            "name": "api_key_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key revoked"
          },
          "400": {
            "description": "Invalid or protected key"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Revoke an API key",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/api-keys/{api_key_id}/rotate": {
      "post": {
        "operationId": "rotateCurrentOrganizationAPIKey",
        "parameters": [
          {
            "in": "path",
            "name": "api_key_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RotatedAPIKey"
                }
              }
            },
            "description": "API key rotated"
          },
          "400": {
            "description": "Invalid or protected key"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Rotate an API key",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/audit-events": {
      "get": {
        "operationId": "listCurrentOrganizationAuditEvents",
        "responses": {
          "200": {
            "description": "Audit events"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List recent audit events",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/audit-events/export": {
      "post": {
        "operationId": "exportCurrentOrganizationAuditEvents",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditExportRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditExport"
                }
              }
            },
            "description": "Audit export generated"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Export audit events for governance workflows",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/developer-free/activate": {
      "post": {
        "operationId": "activateDeveloperFree",
        "responses": {
          "200": {
            "description": "Free developer tier activated"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Activate the free developer tier",
        "tags": [
          "Billing"
        ]
      }
    },
    "/v1/organizations/me/enterprise/ip-allowlist": {
      "get": {
        "operationId": "getCurrentOrganizationIPAllowlist",
        "responses": {
          "200": {
            "description": "IP allowlist configuration"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get enterprise IP allowlist configuration",
        "tags": [
          "Control Plane"
        ]
      },
      "patch": {
        "operationId": "updateCurrentOrganizationIPAllowlist",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IPAllowlistConfiguration"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "IP allowlist configuration updated"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Update enterprise IP allowlist configuration",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/enterprise/saml": {
      "get": {
        "operationId": "getCurrentOrganizationSAMLConfiguration",
        "responses": {
          "200": {
            "description": "SAML configuration"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get SAML SSO control-plane posture",
        "tags": [
          "Control Plane"
        ]
      },
      "patch": {
        "operationId": "updateCurrentOrganizationSAMLConfiguration",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SAMLConfiguration"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "SAML configuration updated"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Update SAML SSO control-plane posture",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/enterprise/scim": {
      "get": {
        "operationId": "getCurrentOrganizationSCIMConfiguration",
        "responses": {
          "200": {
            "description": "SCIM configuration"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get SCIM provisioning control-plane posture",
        "tags": [
          "Control Plane"
        ]
      },
      "patch": {
        "operationId": "updateCurrentOrganizationSCIMConfiguration",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SCIMConfiguration"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "SCIM configuration updated"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Update SCIM provisioning control-plane posture",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/entitlements": {
      "get": {
        "operationId": "listCurrentOrganizationEntitlements",
        "responses": {
          "200": {
            "description": "Entitlement list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List current organization entitlements",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/governance/key-presets": {
      "get": {
        "operationId": "listCurrentOrganizationKeyPresets",
        "responses": {
          "200": {
            "description": "Key presets"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List scoped key presets",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/governance/role-templates": {
      "get": {
        "operationId": "listCurrentOrganizationRoleTemplates",
        "responses": {
          "200": {
            "description": "Role templates"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List governance role templates",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/service-accounts": {
      "post": {
        "operationId": "createCurrentOrganizationServiceAccount",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateServiceAccountRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuedAPIKey"
                }
              }
            },
            "description": "Service-account key issued"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Issue a service-account API key",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/organizations/me/subscription/billing-controls": {
      "patch": {
        "description": "Updates customer-controlled billing and overage settings for the current subscription.\nThis endpoint is additive: it does not replace the Stripe subscription object, but it does\ncontrol SmartAPIs-side presentation and enforcement posture for taxes, coupons, and overage guardrails.\n",
        "operationId": "updateCurrentOrganizationSubscriptionBillingControls",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSubscriptionBillingControlsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Subscription"
                }
              }
            },
            "description": "Updated subscription profile"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Subscription not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Update additive billing controls for the current subscription",
        "tags": [
          "Billing"
        ]
      }
    },
    "/v1/organizations/me/usage": {
      "get": {
        "operationId": "getCurrentOrganizationUsage",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageSummary"
                }
              }
            },
            "description": "Usage summary"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get current-period usage summary",
        "tags": [
          "Control Plane"
        ]
      }
    },
    "/v1/places": {
      "get": {
        "description": "Returns a filtered list of place records for the current organization and plan.\nThis endpoint is intended to be simple enough for direct agent reasoning while still\npreserving source and legal-review posture in the payload.\n",
        "operationId": "listPlaces",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "restaurants": {
                    "value": {
                      "applied_filters": {
                        "limit": 3,
                        "query": "pizza",
                        "region_id": "new-york-city"
                      },
                      "count": 1,
                      "items": [
                        {
                          "category": "restaurant",
                          "display_name": "Joe's Pizza",
                          "legal_review_status": "approved_for_mvp",
                          "municipality": "New York City",
                          "place_id": "place_nyc_001",
                          "region_id": "new-york-city",
                          "source_dataset_id": "dataset_places_nyc_001"
                        }
                      ],
                      "legal_notice": "Use attribution and upstream source posture when redistributing results."
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ItemsResponse"
                }
              }
            },
            "description": "Place list plus applied filters and legal notice"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List legally reviewed places",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/places/nearby": {
      "get": {
        "operationId": "nearbyPlaces",
        "parameters": [
          {
            "in": "query",
            "name": "latitude",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "longitude",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "radius_km",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NearbyPlacesResponse"
                }
              }
            },
            "description": "Nearby place list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Find nearby legally reviewed places",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/places/search": {
      "get": {
        "description": "Explicit Places V2 search route. This is the preferred additive search surface going forward,\nwhile `GET /v1/places` remains supported for compatibility.\n",
        "operationId": "searchPlaces",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemsResponse"
                }
              }
            },
            "description": "Place search list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Search legally reviewed places",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/places/watch": {
      "post": {
        "description": "Accepts a bootstrap watch request for a place record or place query scope.\nThis route is an honest intake surface for future durable watch delivery, not a claim of real-time official monitoring.\n",
        "operationId": "createPlaceWatch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlaceWatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceWatchResponse"
                }
              }
            },
            "description": "Accepted watch registration"
          },
          "400": {
            "description": "Invalid watch request"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Register a bootstrap places watch",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/places/{place_id}": {
      "get": {
        "operationId": "getPlace",
        "parameters": [
          {
            "in": "path",
            "name": "place_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Place record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Place not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed place",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/places/{place_id}/agent-context": {
      "get": {
        "operationId": "getPlaceAgentContext",
        "parameters": [
          {
            "in": "path",
            "name": "place_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceAgentContext"
                }
              }
            },
            "description": "Place agent context"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Place agent context not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get agent-oriented context for one place",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/places/{place_id}/hours": {
      "get": {
        "operationId": "getPlaceHours",
        "parameters": [
          {
            "in": "path",
            "name": "place_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceHours"
                }
              }
            },
            "description": "Structured place hours"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Place hours not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get structured reference hours for one place",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/places/{place_id}/status": {
      "get": {
        "operationId": "getPlaceStatus",
        "parameters": [
          {
            "in": "path",
            "name": "place_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlaceStatus"
                }
              }
            },
            "description": "Place status"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Place status not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get SmartAPIs reference status for one place",
        "tags": [
          "Places"
        ]
      }
    },
    "/v1/products/search": {
      "get": {
        "description": "Returns a filtered list of product reference records for the current organization and plan.\nThis bootstrap surface is designed for product discovery, offer comparison, and price intelligence prototyping.\n",
        "operationId": "listProducts",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "brand",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "gtin",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "coffee": {
                    "value": {
                      "applied_filters": {
                        "brand": "blue bottle",
                        "limit": 5,
                        "query": "coffee",
                        "region_id": "new-york-city"
                      },
                      "count": 1,
                      "items": [
                        {
                          "attribution_text": "NYC Open Data.",
                          "authoritative_language": "en",
                          "brand": "Blue Bottle",
                          "canonical_name": "Blue Bottle Drip Coffee 12oz",
                          "category": "coffee",
                          "description_en": "Medium roast drip coffee reference record.",
                          "display_name_en": "Blue Bottle Drip Coffee 12oz",
                          "gtin": "0123456789012",
                          "last_verified_at": "2026-03-15T00:00:00Z",
                          "legal_review_status": "approved_for_mvp",
                          "license_url": "https://example.org/license",
                          "product_id": "product_nyc_001",
                          "region_id": "new-york-city",
                          "source_dataset": "Product Snapshot",
                          "source_dataset_id": "us_ny_nyc_products_001",
                          "source_publisher": "NYC Open Data",
                          "source_record_url": "https://example.org/products/1",
                          "tags": [
                            "coffee",
                            "grocery"
                          ]
                        }
                      ],
                      "legal_notice": "Bootstrap product results are limited to legally reviewed, commercially cleared reference records with preserved attribution metadata."
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ProductListResponse"
                }
              }
            },
            "description": "Product list plus applied filters and legal notice"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Search legally reviewed product references",
        "tags": [
          "Products"
        ]
      }
    },
    "/v1/products/watch": {
      "post": {
        "description": "Accepts a bootstrap product watch request for a product record or search scope.\nThis route is an honest intake surface for future durable price and offer watch delivery, not a claim of real-time merchant checkout monitoring.\n",
        "operationId": "createProductWatch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductWatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductWatchResponse"
                }
              }
            },
            "description": "Accepted product watch registration"
          },
          "400": {
            "description": "Invalid watch request"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Register a bootstrap product watch",
        "tags": [
          "Products"
        ]
      }
    },
    "/v1/products/{product_id}": {
      "get": {
        "operationId": "getProduct",
        "parameters": [
          {
            "in": "path",
            "name": "product_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            },
            "description": "Product record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Product not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed product reference",
        "tags": [
          "Products"
        ]
      }
    },
    "/v1/products/{product_id}/offers": {
      "get": {
        "operationId": "listProductOffers",
        "parameters": [
          {
            "in": "path",
            "name": "product_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductOfferListResponse"
                }
              }
            },
            "description": "Current offer list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Product offers not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List current offers for one product reference",
        "tags": [
          "Products"
        ]
      }
    },
    "/v1/products/{product_id}/price-history": {
      "get": {
        "operationId": "getProductPriceHistory",
        "parameters": [
          {
            "in": "path",
            "name": "product_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductPriceHistoryResponse"
                }
              }
            },
            "description": "Product price history"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Product price history not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get bootstrap price history for one product reference",
        "tags": [
          "Products"
        ]
      }
    },
    "/v1/regulatory/facilities/{facility_id}": {
      "get": {
        "operationId": "getRegulatoryFacility",
        "parameters": [
          {
            "in": "path",
            "name": "facility_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryFacility"
                }
              }
            },
            "description": "Regulatory facility record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Facility not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed regulated facility",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/regulatory/inspections/search": {
      "get": {
        "operationId": "listRegulatoryInspections",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryInspectionListResponse"
                }
              }
            },
            "description": "Regulatory inspection list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Search legally reviewed regulatory inspection records",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/regulatory/inspections/{record_id}": {
      "get": {
        "operationId": "getRegulatoryInspection",
        "parameters": [
          {
            "in": "path",
            "name": "record_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryInspectionRecord"
                }
              }
            },
            "description": "Regulatory inspection record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Inspection not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed regulatory inspection record",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/regulatory/licenses/search": {
      "get": {
        "operationId": "listRegulatoryLicenses",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "active_restaurant": {
                    "value": {
                      "applied_filters": {
                        "limit": 5,
                        "query": "restaurant",
                        "region_id": "chicago-metro",
                        "status": "active"
                      },
                      "count": 1,
                      "items": [
                        {
                          "advisory_boundary_notice": "Informational public-record summary only; not legal advice.",
                          "attribution_text": "City of Chicago data portal.",
                          "authoritative_language": "en",
                          "expiry_date": "2026-01-01",
                          "facility_id": "facility_chi_001",
                          "issue_date": "2025-01-01",
                          "last_verified_at": "2026-03-15T00:00:00Z",
                          "legal_review_status": "approved_for_mvp",
                          "license_status": "active",
                          "license_type": "food_establishment",
                          "license_url": "https://example.org/license",
                          "municipality": "Chicago",
                          "record_id": "license_chi_001",
                          "region_id": "chicago-metro",
                          "source_dataset_id": "us_il_chi_licenses_001",
                          "source_publisher": "City of Chicago",
                          "source_record_url": "https://example.org/licenses/1",
                          "subject_name": "Example Food Services Inc."
                        }
                      ],
                      "legal_notice": "Regulatory records are public-source reference summaries with preserved provenance and attribution. They do not constitute legal advice, official certification, or government endorsement."
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryLicenseListResponse"
                }
              }
            },
            "description": "Regulatory license list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Search legally reviewed regulatory license records",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/regulatory/licenses/{record_id}": {
      "get": {
        "operationId": "getRegulatoryLicense",
        "parameters": [
          {
            "in": "path",
            "name": "record_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryLicenseRecord"
                }
              }
            },
            "description": "Regulatory license record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "License not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed regulatory license record",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/regulatory/permits/search": {
      "get": {
        "operationId": "listRegulatoryPermits",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryPermitListResponse"
                }
              }
            },
            "description": "Regulatory permit list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Search legally reviewed regulatory permit records",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/regulatory/permits/{record_id}": {
      "get": {
        "operationId": "getRegulatoryPermit",
        "parameters": [
          {
            "in": "path",
            "name": "record_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryPermitRecord"
                }
              }
            },
            "description": "Regulatory permit record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Permit not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed regulatory permit record",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/regulatory/watch": {
      "post": {
        "description": "Accepts a bootstrap regulatory watch request for a public-record scope.\nThis route is an honest intake surface for future durable public-record watch delivery, not a claim of real-time agency filing or enforcement monitoring.\n",
        "operationId": "createRegulatoryWatch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegulatoryWatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatoryWatchResponse"
                }
              }
            },
            "description": "Accepted regulatory watch registration"
          },
          "400": {
            "description": "Invalid watch request"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Register a bootstrap regulatory watch",
        "tags": [
          "Regulatory"
        ]
      }
    },
    "/v1/reports/places/search-snapshot": {
      "get": {
        "description": "Exports a snapshot-backed places search report for technical and non-technical stakeholders.\nThe export includes explicit freshness and provenance labeling and does not imply legal certification or official reporting.\n",
        "operationId": "exportPlacesSearchSnapshotReport",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "enum": [
                "json",
                "csv",
                "markdown",
                "md"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Snapshot report export in selected format"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Export a shareable places snapshot report",
        "tags": [
          "Reports"
        ]
      }
    },
    "/v1/reports/places/search-snapshot/replay/{snapshot_id}": {
      "get": {
        "description": "Replays the places snapshot export for a previously issued `snapshot_id`.\nThis route is deterministic for identical filters and snapshot lineage.\n",
        "operationId": "replayPlacesSearchSnapshotReport",
        "parameters": [
          {
            "in": "path",
            "name": "snapshot_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "enum": [
                "json",
                "csv",
                "markdown",
                "md"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Replay export for the requested snapshot ID"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Snapshot not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Replay a deterministic places snapshot export",
        "tags": [
          "Reports"
        ]
      }
    },
    "/v1/transit/routes": {
      "get": {
        "operationId": "listTransitRoutes",
        "parameters": [
          {
            "in": "query",
            "name": "region_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "examples": {
                  "downtown": {
                    "value": {
                      "applied_filters": {
                        "limit": 5,
                        "query": "sherbrooke",
                        "region_id": "greater-montreal"
                      },
                      "count": 1,
                      "items": [
                        {
                          "agency_name": "STM",
                          "attribution_text": "STM GTFS feed.",
                          "authoritative_language": "fr",
                          "last_verified_at": "2026-03-15T00:00:00Z",
                          "legal_review_status": "approved_for_mvp",
                          "license_url": "https://example.org/license",
                          "mode": "bus",
                          "region_id": "greater-montreal",
                          "route_code": "24",
                          "route_id": "route_mtl_001",
                          "route_long_name": "Sherbrooke Est/Ouest",
                          "route_short_name": "Sherbrooke",
                          "service_area": "Montreal",
                          "source_dataset_id": "ca_qc_mtl_transit_001",
                          "source_feed_format": "gtfs",
                          "source_publisher": "STM",
                          "source_record_url": "https://example.org/routes/24",
                          "tags": [
                            "urban",
                            "frequent"
                          ]
                        }
                      ],
                      "legal_notice": "Bootstrap transit results are limited to legally reviewed public feed references with preserved operator attribution and licensing metadata."
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/TransitListResponse"
                }
              }
            },
            "description": "Transit route list"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List legally reviewed transit routes",
        "tags": [
          "Transit"
        ]
      }
    },
    "/v1/transit/routes/{route_id}": {
      "get": {
        "operationId": "getTransitRoute",
        "parameters": [
          {
            "in": "path",
            "name": "route_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransitRoute"
                }
              }
            },
            "description": "Transit route record"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EntitlementRequired"
          },
          "404": {
            "description": "Route not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one legally reviewed transit route",
        "tags": [
          "Transit"
        ]
      }
    },
    "/v1/watches": {
      "get": {
        "operationId": "listWatches",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Watch"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Durable watches"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "List durable watches for the current organization",
        "tags": [
          "Watches"
        ]
      },
      "post": {
        "operationId": "createWatch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WatchCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Watch"
                }
              }
            },
            "description": "Durable watch created"
          },
          "400": {
            "description": "Invalid watch request"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Create a durable watch",
        "tags": [
          "Watches"
        ]
      }
    },
    "/v1/watches/{watch_id}": {
      "delete": {
        "operationId": "deleteWatch",
        "parameters": [
          {
            "in": "path",
            "name": "watch_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Watch"
                }
              }
            },
            "description": "Deleted watch"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Watch not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Soft-delete one durable watch",
        "tags": [
          "Watches"
        ]
      },
      "get": {
        "operationId": "getWatch",
        "parameters": [
          {
            "in": "path",
            "name": "watch_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Watch"
                }
              }
            },
            "description": "Durable watch"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Watch not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get one durable watch",
        "tags": [
          "Watches"
        ]
      },
      "patch": {
        "operationId": "updateWatch",
        "parameters": [
          {
            "in": "path",
            "name": "watch_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WatchUpdateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Watch"
                }
              }
            },
            "description": "Updated watch"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Watch not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Update mutable watch configuration",
        "tags": [
          "Watches"
        ]
      }
    },
    "/v1/watches/{watch_id}/pause": {
      "post": {
        "operationId": "pauseWatch",
        "parameters": [
          {
            "in": "path",
            "name": "watch_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Watch"
                }
              }
            },
            "description": "Paused watch"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Watch not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Pause one durable watch",
        "tags": [
          "Watches"
        ]
      }
    },
    "/v1/watches/{watch_id}/resume": {
      "post": {
        "operationId": "resumeWatch",
        "parameters": [
          {
            "in": "path",
            "name": "watch_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Watch"
                }
              }
            },
            "description": "Resumed watch"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Watch not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Resume one durable watch",
        "tags": [
          "Watches"
        ]
      }
    },
    "/v1/workflows/regulatory-site-brief/{facility_id}": {
      "get": {
        "description": "Returns a facility-anchored workflow response combining regulatory records with transit and\nenvironment context in one payload. This endpoint is additive and preserves family-level caveats.\n",
        "operationId": "getRegulatorySiteBriefWorkflow",
        "parameters": [
          {
            "in": "path",
            "name": "facility_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 3,
              "maximum": 10,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegulatorySiteBriefWorkflowResponse"
                }
              }
            },
            "description": "Cross-family workflow response"
          },
          "404": {
            "description": "Workflow target not found"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get a cross-family regulatory site brief",
        "tags": [
          "Workflows"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Canonical public host",
      "url": "https://smartapis.net"
    },
    {
      "description": "Development host",
      "url": "https://smartagentapis-api-dev-230006390610.northamerica-northeast1.run.app"
    }
  ],
  "tags": [
    {
      "name": "Discovery"
    },
    {
      "name": "Billing"
    },
    {
      "name": "Control Plane"
    },
    {
      "name": "Legal"
    },
    {
      "name": "Reports"
    },
    {
      "name": "Places"
    },
    {
      "name": "Products"
    },
    {
      "name": "Regulatory"
    },
    {
      "name": "Transit"
    },
    {
      "name": "Environment"
    },
    {
      "name": "Civic"
    },
    {
      "name": "Workflows"
    }
  ]
}