{ "openapi": "3.1.0", "info": { "title": "Homecastr API", "version": "1.12.0", "description": "Probabilistic home value forecasts and canonical public-data resources for US addresses and geographies. Public read endpoints allow anonymous demo access. An API key provides higher limits and account features. Catalog records distinguish metadata, samples, queryable rows, bulk downloads, restricted assets, and unavailable assets.", "contact": { "name": "Homecastr Support", "url": "https://www.homecastr.com/support", "email": "support@homecastr.com" }, "termsOfService": "https://www.homecastr.com/legal", "license": { "name": "Proprietary", "url": "https://www.homecastr.com/legal" } }, "servers": [ { "url": "https://www.homecastr.com", "description": "Production" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Include your Homecastr API key. Omit (or use `hc_demo_public_readonly`) for the free demo tier (50 req/hr per IP). Get a free key and integration docs at https://www.homecastr.com/docs" } }, "schemas": { "FanChartPoint": { "type": "object", "properties": { "year": { "type": "integer", "example": 2027 }, "horizon_months": { "type": "integer", "example": 24 }, "p10": { "type": [ "integer", "null" ] }, "p25": { "type": [ "integer", "null" ] }, "p50": { "type": [ "integer", "null" ] }, "p75": { "type": [ "integer", "null" ] }, "p90": { "type": [ "integer", "null" ] }, "growth_pct": { "type": [ "number", "null" ] }, "growth_dollar": { "type": [ "integer", "null" ] } } }, "BenchmarkCatalogEntry": { "type": "object", "required": [ "asset_id", "asset_class", "support_level", "license_status", "sensitivity", "public_readiness", "phase", "benchmark_role", "license_note", "data_snapshot_id", "training_eligibility", "formats", "endpoint_family" ], "properties": { "asset_id": { "type": "string" }, "asset_class": { "type": "string" }, "current_surface": { "type": "string" }, "support_level": { "type": "string" }, "target_family": { "type": "string" }, "source_family": { "type": "string" }, "license_status": { "type": "string" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "public_readiness": { "type": "string", "enum": [ "launch", "draft", "hold" ] }, "recommended_surface": { "type": "string" }, "phase": { "type": "string" }, "blockers": { "type": "string" }, "next_step": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "benchmark_role": { "type": "string" }, "license_note": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "model_version": { "type": [ "string", "null" ] }, "publication_date": { "type": [ "string", "null" ], "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "formats": { "type": "array", "items": { "type": "string" } }, "endpoint_family": { "type": "string", "enum": [ "catalog", "vintages", "backtests", "sources", "forecast", "download", "none" ] }, "example_path": { "type": [ "string", "null" ] }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "PublicForecastVintageRecord": { "type": "object", "required": [ "asset_id", "vintage_id", "source", "support_level", "benchmark_role", "comparison_method", "geography", "target", "scenario", "year", "data_snapshot_id", "license_note", "training_eligibility" ], "properties": { "asset_id": { "type": "string" }, "vintage_id": { "type": "string" }, "source": { "type": "string" }, "publication_date": { "type": [ "string", "null" ], "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "support_level": { "type": "string" }, "benchmark_role": { "type": "string" }, "comparison_method": { "type": "string" }, "geography": { "type": "string" }, "target": { "type": "string" }, "scenario": { "type": "string" }, "year": { "type": "integer" }, "value": { "type": [ "number", "null" ] }, "notes": { "type": "string" }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "source_file": { "type": [ "string", "null" ] }, "data_snapshot_id": { "type": "string" }, "model_version": { "type": [ "string", "null" ] }, "license_note": { "type": "string" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "BenchmarkBacktestScoreRow": { "type": "object", "required": [ "target", "h0_model", "h0_persistence", "h0_improvement_vs_persistence_pp", "h7_model", "h7_persistence", "h7_improvement_vs_persistence_pp" ], "properties": { "target": { "type": "string" }, "h0_model": { "type": "number" }, "h0_persistence": { "type": "number" }, "h0_improvement_vs_persistence_pp": { "type": "number" }, "h7_model": { "type": "number" }, "h7_persistence": { "type": "number" }, "h7_improvement_vs_persistence_pp": { "type": "number" } } }, "BenchmarkBacktestResult": { "type": "object", "required": [ "asset_id", "benchmark_id", "benchmark_role", "support_level", "origin_year", "horizon_years", "metric", "data_snapshot_id", "license_note", "training_eligibility", "rows" ], "properties": { "asset_id": { "type": "string" }, "benchmark_id": { "type": "string" }, "benchmark_role": { "type": "string" }, "support_level": { "type": "string" }, "origin_year": { "type": "integer" }, "horizon_years": { "type": "array", "items": { "type": "integer" } }, "metric": { "type": "string" }, "publication_date": { "type": [ "string", "null" ], "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "data_snapshot_id": { "type": "string" }, "model_version": { "type": [ "string", "null" ] }, "license_note": { "type": "string" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "interpretation": { "type": "string" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkBacktestScoreRow" } }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "BenchmarkSourceManifest": { "type": "object", "required": [ "asset_id", "manifest_type", "title", "support_level", "benchmark_role", "license_note", "data_snapshot_id", "training_eligibility", "summary" ], "properties": { "asset_id": { "type": "string" }, "manifest_type": { "type": "string" }, "title": { "type": "string" }, "support_level": { "type": "string" }, "benchmark_role": { "type": "string" }, "license_note": { "type": "string" }, "publication_date": { "type": [ "string", "null" ], "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "data_snapshot_id": { "type": "string" }, "model_version": { "type": [ "string", "null" ] }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "summary": { "type": "object" }, "details": { "type": "object" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DataAccessSummary": { "type": "object", "required": [ "visibility", "support_level", "sensitivity", "training_eligibility", "license_status" ], "properties": { "visibility": { "type": "string", "enum": [ "public", "metadata_only", "restricted", "unavailable" ] }, "support_level": { "type": "string" }, "sensitivity": { "type": "string" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "license_status": { "type": "string" } } }, "DataProvenanceSummary": { "type": "object", "required": [ "provenance_id", "data_snapshot_id", "license_note" ], "properties": { "provenance_id": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "publication_date": { "type": [ "string", "null" ], "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "model_version": { "type": [ "string", "null" ] }, "license_note": { "type": "string" } } }, "DataInventoryAssetSummary": { "type": "object", "required": [ "asset_id", "title", "phase", "public_readiness", "benchmark_role", "training_eligibility" ], "properties": { "asset_id": { "type": "string" }, "title": { "type": "string" }, "phase": { "type": "string" }, "public_readiness": { "type": "string" }, "benchmark_role": { "type": "string" }, "model_version": { "type": [ "string", "null" ] }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "example_path": { "type": [ "string", "null" ] } } }, "DataPayloadAvailability": { "type": "object", "required": [ "level", "metadata_available", "sample_rows", "queryable_rows", "bulk_download", "runtime_verification", "reason" ], "properties": { "level": { "type": "string", "enum": [ "metadata_only", "sample_rows", "queryable_rows", "bulk_download", "restricted", "unavailable" ] }, "metadata_available": { "type": "boolean" }, "sample_rows": { "type": "boolean" }, "queryable_rows": { "type": "boolean" }, "bulk_download": { "type": "boolean" }, "runtime_verification": { "type": "string", "enum": [ "contract_declared" ] }, "reason": { "type": "string" } }, "additionalProperties": false }, "DataAssetRecord": { "type": "object", "required": [ "asset_id", "title", "description", "data_family", "raw_source_or_access", "support_level", "targets_or_fields", "pipeline_state", "public_status", "sensitivity", "visibility", "license_status", "recommended_public_surface", "current_surfaces", "canonical_profile", "delivery_targets", "related_artifact_ids", "related_provenance_ids", "gap_or_blocker", "next_step", "provenance", "access", "_links" ], "properties": { "asset_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "data_family": { "type": "string" }, "raw_source_or_access": { "type": "string" }, "example_internal_artifacts": { "type": "string" }, "support_level": { "type": "string" }, "targets_or_fields": { "type": "string" }, "pipeline_state": { "type": "string" }, "public_status": { "type": "string" }, "sensitivity": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "metadata_only", "restricted", "unavailable" ] }, "license_status": { "type": "string" }, "recommended_public_surface": { "type": "string" }, "public_data_inventory_asset": { "type": [ "string", "null" ] }, "payload_availability": { "$ref": "#/components/schemas/DataPayloadAvailability" }, "current_surfaces": { "type": "object", "required": [ "rest", "mcp", "openapi", "docs", "sdk" ], "properties": { "rest": { "type": [ "string", "null" ] }, "mcp": { "type": [ "string", "null" ] }, "openapi": { "type": "string" }, "docs": { "type": "string" }, "sdk": { "type": "string" } } }, "canonical_profile": { "type": "object", "required": [ "source_contract", "canonical_contracts", "raw_retention", "normalization", "engineering", "synthesis_policy" ], "properties": { "source_contract": { "type": "string" }, "canonical_contracts": { "type": "array", "items": { "type": "string" } }, "raw_retention": { "type": "string" }, "normalization": { "type": "array", "items": { "type": "string" } }, "engineering": { "type": "array", "items": { "type": "string" } }, "synthesis_policy": { "type": "string" }, "delivery": { "type": [ "string", "null" ] } } }, "delivery_targets": { "type": "object", "required": [ "rest", "mcp", "openapi", "docs", "sdk", "export_formats" ], "properties": { "rest": { "type": "array", "items": { "type": "string" } }, "mcp": { "type": "array", "items": { "type": "string" } }, "openapi": { "type": "array", "items": { "type": "string" } }, "docs": { "type": "array", "items": { "type": "string" } }, "sdk": { "type": "array", "items": { "type": "string" } }, "export_formats": { "type": "array", "items": { "type": "string" } } } }, "inventory_asset": { "anyOf": [ { "$ref": "#/components/schemas/DataInventoryAssetSummary" }, { "type": "null" } ] }, "related_artifact_ids": { "type": "array", "items": { "type": "string" } }, "related_provenance_ids": { "type": "array", "items": { "type": "string" } }, "gap_or_blocker": { "type": "string" }, "next_step": { "type": "string" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DataSchemaRecord": { "type": "object", "required": [ "canonical_schema_id", "schema_key", "title", "description", "property_count", "required_fields", "referenced_by_families", "artifact_id", "_links" ], "properties": { "canonical_schema_id": { "type": "string" }, "schema_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "json_type": { "type": [ "string", "null" ] }, "property_count": { "type": "integer" }, "required_fields": { "type": "array", "items": { "type": "string" } }, "referenced_by_families": { "type": "array", "items": { "type": "string" } }, "artifact_id": { "type": "string" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DataSchemaDetail": { "allOf": [ { "$ref": "#/components/schemas/DataSchemaRecord" }, { "type": "object", "required": [ "referenced_by_assets", "definition" ], "properties": { "referenced_by_assets": { "type": "array", "items": { "type": "string" } }, "definition": { "type": "object" } } } ] }, "DataProvenanceRecord": { "type": "object", "required": [ "provenance_id", "asset_id", "manifest_type", "title", "support_level", "benchmark_role", "data_snapshot_id", "license_note", "training_eligibility", "summary", "related_artifact_ids", "access", "_links" ], "properties": { "provenance_id": { "type": "string" }, "asset_id": { "type": "string" }, "manifest_type": { "type": "string" }, "title": { "type": "string" }, "support_level": { "type": "string" }, "benchmark_role": { "type": "string" }, "publication_date": { "type": [ "string", "null" ], "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "data_snapshot_id": { "type": "string" }, "model_version": { "type": [ "string", "null" ] }, "license_note": { "type": "string" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "summary": { "type": "object" }, "details": { "type": "object" }, "related_artifact_ids": { "type": "array", "items": { "type": "string" } }, "access": { "type": "object", "required": [ "visibility", "training_eligibility" ], "properties": { "visibility": { "type": "string", "enum": [ "public", "metadata_only", "restricted", "unavailable" ] }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] } } }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DataArtifactManifest": { "type": "object", "required": [ "artifact_id", "title", "description", "artifact_kind", "format", "media_type", "relative_path", "data_snapshot_id", "support_level", "benchmark_role", "license_note", "visibility", "training_eligibility", "_links" ], "properties": { "artifact_id": { "type": "string" }, "owner_asset_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "artifact_kind": { "type": "string" }, "format": { "type": "string" }, "media_type": { "type": "string" }, "relative_path": { "type": "string" }, "size_bytes": { "type": [ "integer", "null" ] }, "publication_date": { "type": [ "string", "null" ], "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "data_snapshot_id": { "type": "string" }, "support_level": { "type": "string" }, "benchmark_role": { "type": "string" }, "license_note": { "type": "string" }, "visibility": { "type": "string", "enum": [ "public", "metadata_only", "restricted", "unavailable" ] }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "CanonicalContractMetadata": { "type": "object", "required": [ "schema_id", "schema_version", "record_id", "asset_id", "data_snapshot_id", "created_at" ], "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "record_id": { "type": "string" }, "asset_id": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "provenance_id": { "type": [ "string", "null" ] }, "access_policy_id": { "type": [ "string", "null" ] } } }, "CanonicalEntityReference": { "type": "object", "required": [ "entity_type", "entity_id", "id_namespace" ], "properties": { "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "id_namespace": { "type": [ "string", "null" ] }, "parent_entity_ids": { "type": "array", "items": { "type": "string" } }, "geometry_id": { "type": [ "string", "null" ] }, "geography_vintage": { "type": [ "string", "null" ] } } }, "CanonicalMetricReference": { "type": "object", "required": [ "metric_id", "target_family", "value_kind", "unit" ], "properties": { "metric_id": { "type": "string" }, "target_family": { "type": [ "string", "null" ] }, "value_kind": { "type": "string", "enum": [ "count", "currency", "index", "percent", "probability", "rate", "area", "distance", "duration", "category", "text", "boolean", "geometry", "embedding" ] }, "unit": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "price_basis": { "type": [ "string", "null" ] }, "aggregation": { "type": [ "string", "null" ], "enum": [ "sum", "mean", "median", "min", "max", "first", "last", "weighted_mean", "mode", "none", null ] }, "seasonal_adjustment": { "type": [ "string", "null" ] } } }, "CanonicalForecastPoint": { "type": "object", "required": [ "forecast_time", "horizon", "horizon_unit", "point", "p10", "p25", "p50", "p75", "p90" ], "properties": { "forecast_time": { "type": "string", "format": "date-time" }, "horizon": { "type": "integer" }, "horizon_unit": { "type": "string", "enum": [ "day", "week", "month", "quarter", "year" ] }, "point": { "type": [ "number", "null" ] }, "p10": { "type": [ "number", "null" ] }, "p25": { "type": [ "number", "null" ] }, "p50": { "type": [ "number", "null" ] }, "p75": { "type": [ "number", "null" ] }, "p90": { "type": [ "number", "null" ] }, "scenario": { "type": [ "string", "null" ] } } }, "CanonicalForecastVintageRecord": { "allOf": [ { "$ref": "#/components/schemas/CanonicalContractMetadata" }, { "type": "object", "required": [ "record_type", "vintage_id", "publisher", "publication_date", "entity", "metric", "scenario", "values", "benchmark_role", "training_eligibility" ], "properties": { "record_type": { "const": "forecast_vintage" }, "vintage_id": { "type": "string" }, "publisher": { "type": "string" }, "publication_date": { "type": "string", "format": "date" }, "retrieval_date": { "type": [ "string", "null" ], "format": "date" }, "entity": { "$ref": "#/components/schemas/CanonicalEntityReference" }, "metric": { "$ref": "#/components/schemas/CanonicalMetricReference" }, "scenario": { "type": "string" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalForecastPoint" } }, "benchmark_role": { "type": "string" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] } } } ] }, "CanonicalBenchmarkScore": { "type": "object", "required": [ "metric_name", "value", "aggregation_level", "target", "horizon", "baseline_name", "improvement", "sample_count", "confidence_interval" ], "properties": { "metric_name": { "type": "string" }, "value": { "type": [ "number", "null" ] }, "aggregation_level": { "type": "string" }, "target": { "type": [ "string", "null" ] }, "horizon": { "type": [ "integer", "null" ] }, "baseline_name": { "type": [ "string", "null" ] }, "improvement": { "type": [ "number", "null" ] }, "sample_count": { "type": [ "integer", "null" ] }, "confidence_interval": { "anyOf": [ { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, { "type": "null" } ] } } }, "CanonicalBenchmarkResultRecord": { "allOf": [ { "$ref": "#/components/schemas/CanonicalContractMetadata" }, { "type": "object", "required": [ "record_type", "benchmark_id", "dataset_snapshot_ids", "evaluation_cutoff", "split_definition", "model_versions", "scores", "reproducibility" ], "properties": { "record_type": { "const": "benchmark_result" }, "benchmark_id": { "type": "string" }, "dataset_snapshot_ids": { "type": "array", "items": { "type": "string" } }, "evaluation_cutoff": { "type": "string", "format": "date-time" }, "split_definition": { "type": "string" }, "model_versions": { "type": "array", "items": { "type": "string" } }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalBenchmarkScore" } }, "reproducibility": { "type": "object", "required": [ "code_version", "config_id", "environment_id", "artifact_ids" ], "properties": { "code_version": { "type": "string" }, "config_id": { "type": "string" }, "environment_id": { "type": [ "string", "null" ] }, "artifact_ids": { "type": "array", "items": { "type": "string" } } } } } } ] }, "CensusBpsCountyMonthlyPartition": { "type": "object", "required": [ "year", "month", "kind", "source_uri", "normalized_uri", "public_path", "record_count", "bytes", "metric_totals" ], "properties": { "year": { "type": "integer", "example": 2026 }, "month": { "type": "integer", "example": 5 }, "kind": { "type": "string", "enum": [ "current_month", "year_to_date" ], "example": "current_month" }, "source_uri": { "type": "string" }, "source_bytes": { "type": "integer" }, "source_etag": { "type": [ "string", "null" ] }, "source_last_modified": { "type": [ "string", "null" ], "format": "date-time" }, "normalized_uri": { "type": "string" }, "public_path": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "record_count": { "type": "integer" }, "bytes": { "type": "integer" }, "metric_totals": { "type": "object", "properties": { "total_buildings": { "type": "integer" }, "total_units": { "type": "integer" }, "total_value_usd": { "type": "integer" } }, "additionalProperties": false } } }, "CensusBpsCountyMonthlyManifestSummary": { "type": "object", "required": [ "schema_id", "generated_at", "run_id", "source_id", "normalized_prefix_uri", "partition_count", "record_count", "latest_current_month", "settlement_policy" ], "properties": { "schema_id": { "type": "string", "example": "hc.permit_county_month_manifest.v1" }, "generated_at": { "type": "string", "format": "date-time" }, "run_id": { "type": "string" }, "source_id": { "type": "string", "example": "census_bps_county_monthly_ascii" }, "source_official_url": { "type": "string", "format": "uri" }, "source_prefix_uri": { "type": "string" }, "normalized_prefix_uri": { "type": "string" }, "latest_manifest_uri": { "type": "string" }, "manifest_uri": { "type": "string" }, "latest_run_manifest_uri": { "type": "string" }, "latest_data_manifest_uri": { "type": "string" }, "normalization_version": { "type": "string" }, "source_object_count": { "type": "integer" }, "partition_count": { "type": "integer" }, "record_count": { "type": "integer" }, "partition_bytes": { "type": "integer" }, "latest_current_month": { "$ref": "#/components/schemas/CensusBpsCountyMonthlyPartition" }, "metric_totals": { "type": "object", "additionalProperties": { "type": "integer" } }, "settlement_policy": { "type": "object", "properties": { "resolution_grain": { "type": "string" }, "resolution_basis": { "type": "string" }, "canonical_value": { "type": "string" }, "revision_policy": { "type": "string" }, "independent_verification": { "type": "string", "format": "uri" } }, "additionalProperties": false } } }, "CensusBpsCountyMonthlyRecord": { "type": "object", "required": [ "schema_id", "record_id", "source_id", "source_snapshot_id", "source_uri", "geography", "period", "metrics", "quality_flags", "normalization_version" ], "properties": { "schema_id": { "type": "string", "example": "hc.permit_county_month.v1" }, "record_id": { "type": "string" }, "source_id": { "type": "string", "example": "census_bps_county_monthly_ascii" }, "source_record_id": { "type": "string" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "source_official_url": { "type": "string", "format": "uri" }, "normalization_version": { "type": "string" }, "geography": { "type": "object", "properties": { "entity_type": { "type": "string", "const": "county" }, "county_fips": { "type": "string", "example": "48201" }, "state_fips": { "type": "string", "example": "48" }, "county_code": { "type": "string" }, "county_name": { "type": [ "string", "null" ] }, "region_code": { "type": [ "string", "null" ] }, "division_code": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "period": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" }, "survey_date": { "type": "string" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "kind": { "type": "string", "enum": [ "current_month", "year_to_date" ] }, "source_vintage": { "type": "string" }, "retrieved_at": { "type": [ "string", "null" ], "format": "date-time" }, "available_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "metrics": { "type": "object", "additionalProperties": true }, "quality_flags": { "type": "array", "items": { "type": "string" } }, "missing_reason": { "type": [ "string", "null" ] }, "published_at": { "type": "string", "format": "date-time" } } }, "CensusBpsCountyMonthlyResponse": { "type": "object", "required": [ "schema_id", "asset_id", "source_id", "data_snapshot_id", "record_count", "filters", "manifest", "partitions", "records", "access", "_links" ], "properties": { "schema_id": { "type": "string", "example": "hc.permit_county_month.v1" }, "asset_id": { "type": "string", "example": "context.census_building_permits" }, "source_id": { "type": "string", "example": "census_bps_county_monthly_ascii" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": true }, "manifest": { "$ref": "#/components/schemas/CensusBpsCountyMonthlyManifestSummary" }, "partitions": { "type": "array", "items": { "$ref": "#/components/schemas/CensusBpsCountyMonthlyPartition" } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/CensusBpsCountyMonthlyRecord" } }, "access": { "type": "object", "additionalProperties": { "type": "string" } }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "tip": { "type": "string" }, "example": { "type": "string" } }, "required": [ "error" ] }, "DataEntityRecord": { "allOf": [ { "$ref": "#/components/schemas/CanonicalEntityReference" }, { "type": "object", "required": [ "display_name", "support_level", "labels", "aliases", "source_asset_ids" ], "properties": { "display_name": { "type": "string" }, "support_level": { "type": "string" }, "labels": { "type": "object", "additionalProperties": { "type": "string" } }, "aliases": { "type": "array", "items": { "type": "string" } }, "source_asset_ids": { "type": "array", "items": { "type": "string" } } } } ] }, "DataCrosswalkRecord": { "type": "object", "required": [ "source_entity", "target_entity", "relation_type", "support_level", "source_asset_id" ], "properties": { "source_entity": { "$ref": "#/components/schemas/CanonicalEntityReference" }, "target_entity": { "$ref": "#/components/schemas/CanonicalEntityReference" }, "relation_type": { "type": "string", "enum": [ "contains", "maps_to_primary", "belongs_to" ] }, "weight": { "type": [ "number", "null" ] }, "support_level": { "type": "string" }, "source_asset_id": { "type": "string" }, "notes": { "type": [ "string", "null" ] } } }, "DataSourceRecord": { "type": "object", "required": [ "source_id", "source_name", "source_family", "source_group", "source_tier", "source_status", "panel_status", "authority", "official_url", "official_urls", "license_status", "sensitivity", "geography", "resolution", "cadence", "format", "raw_retention", "normalization", "panels", "targets", "public_readiness", "training_eligibility", "provenance_id", "evidence_file", "notes", "access", "_links" ], "properties": { "source_id": { "type": "string", "example": "source.hcad_houston.assessor" }, "source_name": { "type": "string", "example": "Harris Central Appraisal District parcel data" }, "source_family": { "type": "string", "example": "assessor_tax" }, "source_group": { "type": "string", "example": "raw_single_source_benchmark_registry" }, "source_tier": { "type": "string", "example": "used_in_panel" }, "source_status": { "type": "string", "example": "used" }, "panel_status": { "type": "string", "example": "panelized" }, "authority": { "type": "string", "example": "Harris Central Appraisal District" }, "official_url": { "type": [ "string", "null" ], "example": "https://pdata.hcad.org/" }, "official_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "license_status": { "type": "string", "example": "public_source_metadata_only" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "geography": { "type": "string", "example": "US-TX-Harris" }, "resolution": { "type": "string", "example": "parcel" }, "cadence": { "type": "string", "example": "annual" }, "temporal_start": { "type": [ "string", "null" ] }, "temporal_end": { "type": [ "string", "null" ] }, "format": { "type": "string", "example": "csv|zip|api" }, "raw_retention": { "type": "string", "example": "metadata_public_raw_private" }, "normalization": { "type": "array", "items": { "type": "string" } }, "panels": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "type": "string" } }, "public_readiness": { "type": "string", "example": "metadata_public_raw_hold" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "provenance_id": { "type": "string", "example": "prov:source.hcad_houston.assessor" }, "evidence_file": { "type": "string", "example": "packages/pipeline/scripts/pipeline/training/raw_single_source_benchmark_registry.yaml" }, "notes": { "type": "string" }, "payload_availability": { "$ref": "#/components/schemas/DataPayloadAvailability" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DataPanelLineageRecord": { "type": "object", "required": [ "panel_id", "panel_name", "source_id", "source_role", "join_keys", "join_method", "transform_id", "availability_rule", "output_fields", "status", "evidence_file", "source", "_links" ], "properties": { "panel_id": { "type": "string", "example": "panel.acs_nationwide" }, "panel_name": { "type": "string", "example": "ACS nationwide tract panel" }, "source_id": { "type": "string", "example": "census.acs.tract_5yr" }, "source_role": { "type": "string", "example": "primary_target_panel" }, "join_keys": { "type": "array", "items": { "type": "string" } }, "join_method": { "type": "string", "example": "entity_year_join" }, "transform_id": { "type": "string", "example": "transform.acs_nationwide_panel" }, "availability_rule": { "type": "string", "example": "as_of_source_vintage" }, "output_fields": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "example": "active" }, "evidence_file": { "type": "string", "example": "packages/pipeline/scripts/pipeline/training/raw_single_source_benchmark_registry.yaml" }, "source": { "type": [ "object", "null" ], "properties": { "source_name": { "type": "string" }, "source_family": { "type": "string" }, "official_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "public_readiness": { "type": "string" }, "license_status": { "type": "string" } } }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "DataCoverageSummary": { "type": "object", "required": [ "source_count", "lineage_edge_count", "panel_count", "official_link_count", "missing_official_url_count", "source_coverage_index_count", "by_source_tier", "by_source_status", "by_source_family", "by_license_status", "by_geography", "by_resolution", "source_index", "map", "panels" ], "properties": { "source_count": { "type": "integer", "example": 107 }, "lineage_edge_count": { "type": "integer", "example": 140 }, "panel_count": { "type": "integer", "example": 16 }, "official_link_count": { "type": "integer", "example": 110 }, "missing_official_url_count": { "type": "integer", "example": 2 }, "source_coverage_index_count": { "type": "integer", "example": 107 }, "by_source_tier": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_source_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_source_family": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_license_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_geography": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_resolution": { "type": "object", "additionalProperties": { "type": "integer" } }, "source_index": { "type": "object", "required": [ "record_count", "by_geometry_role", "by_native_boundary_status", "by_redistributable_geometry", "by_public_readiness", "by_training_eligibility" ], "properties": { "record_count": { "type": "integer", "example": 107 }, "by_geometry_role": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_native_boundary_status": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_redistributable_geometry": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_public_readiness": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_training_eligibility": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "map": { "type": "object", "required": [ "artifact_id", "data_snapshot_id", "region_count", "reference_boundary_count", "generalized_region_count", "source_count", "official_link_count", "by_geometry_role", "by_coverage_kind", "top_regions" ], "properties": { "artifact_id": { "type": "string", "example": "public-data.source_coverage_map_geojson" }, "data_snapshot_id": { "type": [ "string", "null" ], "example": "public-data.source_coverage_map.2026-07-17" }, "region_count": { "type": "integer", "example": 20 }, "reference_boundary_count": { "type": "integer", "example": 16 }, "generalized_region_count": { "type": "integer", "example": 4 }, "source_count": { "type": "integer", "example": 107 }, "official_link_count": { "type": "integer", "example": 110 }, "by_geometry_role": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_coverage_kind": { "type": "object", "additionalProperties": { "type": "integer" } }, "top_regions": { "type": "array", "items": { "type": "object", "required": [ "region_id", "label", "coverage_kind", "geometry_role", "source_count", "official_link_count", "source_family_count", "panel_count", "reference_boundary_names", "source_index_href" ], "properties": { "region_id": { "type": "string", "example": "coverage.arizona_phoenix_maricopa_pinal" }, "label": { "type": "string", "example": "Phoenix / Maricopa / Pinal" }, "coverage_kind": { "type": "string", "example": "Metro / county" }, "geometry_role": { "type": "string", "example": "reference_boundary" }, "source_count": { "type": "integer", "example": 47 }, "official_link_count": { "type": "integer", "example": 46 }, "source_family_count": { "type": "integer", "example": 7 }, "panel_count": { "type": "integer", "example": 2 }, "reference_boundary_names": { "type": "array", "items": { "type": "string" } }, "source_index_href": { "type": "string", "example": "/api/v1/data/coverage/sources?coverage_feature_id=coverage.arizona_phoenix_maricopa_pinal" } } } } } }, "panels": { "type": "array", "items": { "type": "object", "properties": { "panel_id": { "type": "string" }, "panel_name": { "type": "string" }, "source_count": { "type": "integer" }, "source_families": { "type": "array", "items": { "type": "string" } }, "source_tiers": { "type": "array", "items": { "type": "string" } }, "public_readiness": { "type": "array", "items": { "type": "string" } } } } } } }, "SourceCoverageMapFeature": { "type": "object", "required": [ "type", "id", "geometry", "properties" ], "properties": { "type": { "type": "string", "enum": [ "Feature" ] }, "id": { "type": "string", "example": "coverage.arizona_phoenix_maricopa_pinal" }, "geometry": { "type": "object", "required": [ "type", "coordinates" ], "properties": { "type": { "type": "string", "enum": [ "Polygon", "MultiPolygon" ] }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" } } } } } }, "properties": { "type": "object", "required": [ "region_id", "coverage_group", "short_label", "coverage_kind", "geography_tokens", "source_count", "official_link_count", "source_ids", "source_names", "official_urls", "panels", "geometry_role", "geometry_source", "geometry_note" ], "properties": { "region_id": { "type": "string", "example": "coverage.arizona_phoenix_maricopa_pinal" }, "coverage_group": { "type": "string", "example": "Phoenix / Maricopa / Pinal" }, "short_label": { "type": "string", "example": "Phoenix" }, "coverage_kind": { "type": "string", "example": "Metro / county" }, "geography_tokens": { "type": "array", "items": { "type": "string" } }, "source_count": { "type": "integer", "example": 44 }, "official_link_count": { "type": "integer", "example": 45 }, "source_ids": { "type": "array", "items": { "type": "string" } }, "source_names": { "type": "array", "items": { "type": "string" } }, "official_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "source_families": { "type": "array", "items": { "type": "string" } }, "source_statuses": { "type": "array", "items": { "type": "string" } }, "panel_statuses": { "type": "array", "items": { "type": "string" } }, "license_statuses": { "type": "array", "items": { "type": "string" } }, "public_readiness": { "type": "array", "items": { "type": "string" } }, "training_eligibility": { "type": "array", "items": { "type": "string" } }, "geography_labels": { "type": "array", "items": { "type": "string" } }, "panels": { "type": "array", "items": { "type": "string" } }, "geometry_role": { "type": "string", "enum": [ "reference_boundary", "generalized_selection_region" ], "example": "reference_boundary" }, "geometry_source": { "type": "string", "example": "U.S. Census Bureau TIGERweb generalized counties (https://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweb/State_County/MapServer/13)" }, "reference_boundary_ids": { "type": "array", "items": { "type": "string" }, "example": [ "04013", "04021" ] }, "reference_boundary_names": { "type": "array", "items": { "type": "string" }, "example": [ "Maricopa County", "Pinal County" ] }, "reference_boundary_source": { "type": [ "string", "null" ], "example": "U.S. Census Bureau TIGERweb generalized counties" }, "reference_boundary_url": { "type": [ "string", "null" ], "format": "uri", "example": "https://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweb/State_County/MapServer/13" }, "reference_boundary_retrieved_at": { "type": [ "string", "null" ], "format": "date", "example": "2026-07-17" }, "reference_boundary_artifact_id": { "type": [ "string", "null" ], "example": "public-data.reference_boundaries_geojson" }, "geometry_note": { "type": "string", "example": "Census county reference boundary for Maricopa and Pinal counties; not source-native geometry." } } } } }, "SourceCoverageMap": { "type": "object", "required": [ "type", "name", "properties", "features" ], "properties": { "type": { "type": "string", "enum": [ "FeatureCollection" ] }, "name": { "type": "string", "example": "Homecastr public source coverage map" }, "properties": { "type": "object", "required": [ "asset_id", "schema_id", "schema_version", "data_snapshot_id", "publication_date", "support_level", "benchmark_role", "license_note", "source_inventory_artifact_id", "reference_boundary_artifact_id", "geometry_note", "source_count", "official_link_count", "region_count", "reference_boundary_count", "generalized_region_count" ], "properties": { "asset_id": { "type": "string", "example": "public-data.source_coverage_map_geojson" }, "schema_id": { "type": "string", "example": "hc.source_coverage_map.v1" }, "schema_version": { "type": "string", "example": "1.0.0" }, "data_snapshot_id": { "type": "string", "example": "public-data.source_coverage_map.2026-07-17" }, "publication_date": { "type": "string", "format": "date", "example": "2026-07-17" }, "support_level": { "type": "string", "example": "global|regional" }, "benchmark_role": { "type": "string", "example": "source_coverage_visualization" }, "license_note": { "type": "string" }, "source_inventory_path": { "type": "string", "example": "docs/public-data/source-inventory.tsv" }, "source_inventory_artifact_id": { "type": "string", "example": "public-data.source_inventory_tsv" }, "completion_audit_artifact_id": { "type": "string", "example": "public-data.completion_audit_md" }, "reference_boundary_artifact_id": { "type": "string", "example": "public-data.reference_boundaries_geojson" }, "geometry_note": { "type": "string" }, "source_count": { "type": "integer", "example": 107 }, "official_link_count": { "type": "integer", "example": 110 }, "region_count": { "type": "integer", "example": 20 }, "reference_boundary_count": { "type": "integer", "example": 16 }, "generalized_region_count": { "type": "integer", "example": 4 } } }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/SourceCoverageMapFeature" } } } }, "DataSourceCoverageRecord": { "type": "object", "required": [ "source_id", "source_name", "source_family", "source_status", "coverage_feature_ids", "coverage_groups", "coverage_kinds", "declared_geography", "geography_tokens", "native_resolution", "native_format", "panels", "targets", "official_urls", "license_status", "sensitivity", "public_readiness", "training_eligibility", "geometry_surface", "coverage_geometry_role", "reference_boundary_ids", "reference_boundary_names", "reference_boundary_source", "reference_boundary_url", "native_boundary_status", "redistributable_geometry", "boundary_access_note", "geometry_notes", "related_artifact_ids", "next_step", "access", "_links" ], "properties": { "source_id": { "type": "string", "example": "az.maricopa_parcels" }, "source_name": { "type": "string", "example": "Maricopa County Parcels" }, "source_family": { "type": "string", "example": "maricopa_assessor_parcels" }, "source_status": { "type": "string", "example": "candidate" }, "coverage_feature_ids": { "type": "array", "items": { "type": "string" } }, "coverage_groups": { "type": "array", "items": { "type": "string" } }, "coverage_kinds": { "type": "array", "items": { "type": "string" } }, "declared_geography": { "type": "string", "example": "US-AZ-Phoenix-MSA|US-AZ-Maricopa|US-AZ-Pinal" }, "geography_tokens": { "type": "array", "items": { "type": "string" } }, "native_resolution": { "type": "string", "example": "parcel|tract|taz|raz|mpa" }, "native_format": { "type": "string", "example": "arcgis_rest" }, "panels": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "type": "string" } }, "official_urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "license_status": { "type": "string", "example": "public_source_metadata_only" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ] }, "public_readiness": { "type": "string", "example": "metadata_public" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "geometry_surface": { "type": "string", "example": "reference_boundary_plus_native_boundary_candidate" }, "coverage_geometry_role": { "type": "array", "items": { "type": "string" }, "example": [ "reference_boundary" ] }, "reference_boundary_ids": { "type": "array", "items": { "type": "string" }, "example": [ "04013", "04021" ] }, "reference_boundary_names": { "type": "array", "items": { "type": "string" }, "example": [ "Maricopa County", "Pinal County" ] }, "reference_boundary_source": { "type": "array", "items": { "type": "string" }, "example": [ "U.S. Census Bureau TIGERweb generalized counties" ] }, "reference_boundary_url": { "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "https://tigerweb.geo.census.gov/arcgis/rest/services/TIGERweb/State_County/MapServer/13" ] }, "native_boundary_status": { "type": "string", "example": "native_boundary_candidate_terms_review_required" }, "redistributable_geometry": { "type": "string", "example": "public_reference_coverage_feature_only_until_source_terms_review" }, "boundary_access_note": { "type": "string" }, "geometry_notes": { "type": "array", "items": { "type": "string" } }, "related_artifact_ids": { "type": "array", "items": { "type": "string" } }, "next_step": { "type": "string" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "PublicRecordsAcquisitionRecord": { "type": "object", "required": [ "lane_id", "source_family", "source_families", "geography", "geography_tokens", "current_status", "durable_cloud_evidence", "object_count", "byte_count", "public_route_evidence", "records_law_gate", "holdbacks", "next_step", "fold_in_source", "benchmark_role", "training_eligibility", "related_artifact_ids", "access", "_links" ], "properties": { "lane_id": { "type": "string", "example": "georgia_permit_public_routes" }, "source_family": { "type": "string", "example": "permits_planning_development_pipeline" }, "source_families": { "type": "array", "items": { "type": "string" } }, "geography": { "type": "string", "example": "US-GA-Fulton-Johns-Creek|US-GA-Douglasville|US-GA-Cobb" }, "geography_tokens": { "type": "array", "items": { "type": "string" } }, "current_status": { "type": "string", "example": "public_r2_partial_downstream_screen_complete" }, "durable_cloud_evidence": { "type": "string", "example": "r2://properlytic-raw-data/source_review/public_records/..." }, "object_count": { "type": "string", "example": "66 public-payload objects; 5 route-snapshot objects" }, "byte_count": { "type": "string", "example": "13744090 public-payload bytes" }, "public_route_evidence": { "type": "string" }, "records_law_gate": { "type": "string", "example": "closed_no_send_ready_candidate" }, "holdbacks": { "type": "string" }, "next_step": { "type": "string" }, "fold_in_source": { "type": "string", "example": "b14c docs/public-records-goal-resume-2026-07-17.md" }, "benchmark_role": { "type": "string", "example": "source_acquisition_evidence" }, "training_eligibility": { "type": "string", "enum": [ "benchmark_only", "consumer_feed", "training_candidate", "holdback" ] }, "related_artifact_ids": { "type": "array", "items": { "type": "string" } }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Fast41ProjectManifestSummary": { "type": "object", "required": [ "schema_id", "generated_at", "run_id", "source_id", "source_official_url", "full_dataset_official_url", "source_snapshot_id", "source_dataset_id", "source_dataset_name", "normalized_prefix_uri", "project_payload_uri", "project_payload_public_path", "project_payload_bytes", "source_row_count", "project_count", "status_counts", "sector_counts", "state_counts", "settlement_policy" ], "properties": { "schema_id": { "type": "string", "example": "hc.fast41_project_manifest.v1" }, "generated_at": { "type": "string", "format": "date-time" }, "run_id": { "type": "string", "example": "20260718T184450+0000" }, "source_id": { "type": "string", "example": "fast41_project_milestones" }, "source_official_url": { "type": "string", "format": "uri" }, "full_dataset_official_url": { "type": "string", "format": "uri" }, "source_snapshot_id": { "type": "string" }, "source_dataset_id": { "type": "string", "example": "fh3k-bqsc" }, "source_dataset_name": { "type": "string", "example": "FAST-41 Projects Data" }, "source_rows_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_publication_date": { "type": [ "string", "null" ], "format": "date-time" }, "normalized_prefix_uri": { "type": "string" }, "project_payload_uri": { "type": "string" }, "project_payload_public_path": { "type": "string" }, "project_payload_bytes": { "type": "integer" }, "source_row_count": { "type": "integer" }, "project_count": { "type": "integer" }, "status_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "sector_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "state_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "settlement_policy": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Fast41ProjectRecord": { "type": "object", "required": [ "schema_id", "record_id", "source_id", "source_record_id", "source_snapshot_id", "source_uri", "source_metadata_uri", "source_official_url", "full_dataset_official_url", "normalization_version", "project", "location", "source_row_count", "visible_field_variant_count", "quality_flags", "published_at" ], "properties": { "schema_id": { "type": "string", "example": "hc.fast41_project.v1" }, "record_id": { "type": "string", "example": "fast41_project_milestones:107581" }, "source_id": { "type": "string", "example": "fast41_project_milestones" }, "source_record_id": { "type": "string" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "source_metadata_uri": { "type": "string" }, "source_official_url": { "type": "string", "format": "uri" }, "full_dataset_official_url": { "type": "string", "format": "uri" }, "normalization_version": { "type": "string" }, "project": { "type": "object", "properties": { "project_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "sector": { "type": [ "string", "null" ] }, "sector_type": { "type": [ "string", "null" ] }, "lead_agency": { "type": [ "string", "null" ] }, "lead_agency_bureau": { "type": [ "string", "null" ] } } }, "location": { "type": "object", "properties": { "state": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "street_address": { "type": [ "string", "null" ] }, "full_address": { "type": [ "string", "null" ] }, "latlong_wkt": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } }, "source_row_count": { "type": "integer" }, "visible_field_variant_count": { "type": "integer" }, "quality_flags": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "format": "date-time" } } }, "Fast41ProjectResponse": { "type": "object", "required": [ "schema_id", "asset_id", "source_id", "data_snapshot_id", "record_count", "filters", "manifest", "records", "access", "_links" ], "properties": { "schema_id": { "type": "string", "example": "hc.fast41_project.v1" }, "asset_id": { "type": "string", "example": "context.fast41_federal_permitting" }, "source_id": { "type": "string", "example": "fast41_project_milestones" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": true }, "manifest": { "$ref": "#/components/schemas/Fast41ProjectManifestSummary" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/Fast41ProjectRecord" } }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EpaEchoNpdesSewerOverflowManifestSummary": { "type": "object", "required": [ "schema_id", "generated_at", "run_id", "source_id", "source_official_url", "source_page_url", "source_snapshot_id", "source_uri", "normalized_prefix_uri", "event_payload_uri", "event_payload_public_path", "event_payload_bytes", "table_counts", "event_count", "permit_count", "events_with_coordinates", "events_with_volume", "reported_volume_gallons_sum", "state_counts", "event_type_counts", "structure_type_counts", "settlement_policy" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_sewer_overflow_manifest.v1" }, "generated_at": { "type": "string", "format": "date-time" }, "run_id": { "type": "string", "example": "20260718T190943+0000" }, "source_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_current" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "normalized_prefix_uri": { "type": "string" }, "event_payload_uri": { "type": "string" }, "event_payload_public_path": { "type": "string" }, "event_payload_bytes": { "type": "integer", "example": 18036874 }, "table_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "event_count": { "type": "integer", "example": 4685 }, "permit_count": { "type": "integer", "example": 639 }, "events_with_coordinates": { "type": "integer", "example": 3092 }, "events_with_volume": { "type": "integer", "example": 3374 }, "reported_volume_gallons_sum": { "type": "number", "example": 7521279853.5 }, "state_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "event_type_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "structure_type_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "settlement_policy": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EpaEchoNpdesSewerOverflowRecord": { "type": "object", "required": [ "schema_id", "record_id", "source_id", "source_record_id", "source_snapshot_id", "source_uri", "source_official_url", "source_page_url", "normalization_version", "permit", "report", "event", "location", "related", "quality_flags", "published_at" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_sewer_overflow_event.v1" }, "record_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_current:4199" }, "source_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_current" }, "source_record_id": { "type": "string" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "normalization_version": { "type": "string" }, "permit": { "type": "object", "properties": { "permit_id": { "type": [ "string", "null" ] }, "state_code": { "type": [ "string", "null" ] }, "collection_system_identifier": { "type": [ "string", "null" ] }, "permitted_feature_identifier": { "type": [ "string", "null" ] }, "collection_system": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "owner_type_code": { "type": [ "string", "null" ] }, "owner_type_desc": { "type": [ "string", "null" ] }, "population": { "type": [ "number", "null" ] }, "percent_combined_sewer_system": { "type": [ "number", "null" ] } } } } }, "report": { "type": "object", "properties": { "program_report_form_set_id": { "type": [ "string", "null" ] }, "program_report_form_id": { "type": [ "string", "null" ] }, "event_id_external": { "type": [ "string", "null" ] }, "received_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "payload_id": { "type": [ "string", "null" ] }, "transaction_type": { "type": [ "string", "null" ] }, "event_transaction_type": { "type": [ "string", "null" ] }, "electronic_submission_type_code": { "type": [ "string", "null" ] }, "electronic_submission_type_desc": { "type": [ "string", "null" ] } } }, "event": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "reporting_requirement_code": { "type": [ "string", "null" ] }, "reporting_requirement_desc": { "type": [ "string", "null" ] }, "wet_weather": { "type": [ "boolean", "null" ] }, "structure_type_code": { "type": [ "string", "null" ] }, "structure_type_desc": { "type": [ "string", "null" ] }, "structure_type_other_text": { "type": [ "string", "null" ] }, "duration_hours": { "type": [ "number", "null" ] }, "start_datetime": { "type": [ "string", "null" ] }, "end_datetime": { "type": [ "string", "null" ] }, "discharge_quantification_method_code": { "type": [ "string", "null" ] }, "discharge_quantification_method_desc": { "type": [ "string", "null" ] }, "discharge_volume_gallons": { "type": [ "number", "null" ] }, "discharge_rate_gph": { "type": [ "number", "null" ] }, "anticipated_bypass_text": { "type": [ "string", "null" ] }, "anticipated_bypass_expect_limit_violation": { "type": [ "boolean", "null" ] }, "anticipated_bypass_expect_limit_violation_text": { "type": [ "string", "null" ] } } }, "location": { "type": "object", "properties": { "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } }, "related": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "causes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "impacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "corrective_actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "receiving_waters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "treatment_codes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "quality_flags": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "format": "date-time" } } }, "EpaEchoNpdesSewerOverflowResponse": { "type": "object", "required": [ "schema_id", "asset_id", "source_id", "data_snapshot_id", "record_count", "filters", "manifest", "records", "access", "_links" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_sewer_overflow_event.v1" }, "asset_id": { "type": "string", "example": "context.epa_echo_npdes_sewer_overflows" }, "source_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_current" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": true }, "manifest": { "$ref": "#/components/schemas/EpaEchoNpdesSewerOverflowManifestSummary" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/EpaEchoNpdesSewerOverflowRecord" } }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EpaEchoNpdesOutfallPartition": { "type": "object", "required": [ "state_code", "permit_status_code", "key", "public_path", "record_count", "bytes" ], "properties": { "state_code": { "type": "string", "example": "TX" }, "permit_status_code": { "type": "string", "example": "EFF" }, "key": { "type": "string" }, "public_path": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "record_count": { "type": "integer", "example": 5000 }, "bytes": { "type": "integer", "example": 498402 }, "uncompressed_bytes": { "type": "integer", "example": 12408622 }, "content_encoding": { "type": "string", "example": "gzip" } } }, "EpaEchoNpdesOutfallManifestSummary": { "type": "object", "required": [ "schema_id", "generated_at", "run_id", "source_id", "source_official_url", "source_page_url", "source_snapshot_id", "source_uri", "normalized_prefix_uri", "source_compressed_bytes", "record_count", "partition_count", "partition_bytes", "chunk_size", "state_counts", "permit_status_code_counts", "permit_status_desc_counts", "permit_type_desc_counts", "component_counts", "current_violation_counts", "cwa_status_counts", "major_minor_counts", "query_policy", "settlement_policy" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_outfall_manifest.v1" }, "generated_at": { "type": "string", "format": "date-time" }, "run_id": { "type": "string", "example": "20260718T193625+0000" }, "source_id": { "type": "string", "example": "epa_echo_npdes_outfalls_layer" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "normalized_prefix_uri": { "type": "string" }, "source_compressed_bytes": { "type": "integer", "example": 49038467 }, "record_count": { "type": "integer", "example": 820538 }, "partition_count": { "type": "integer", "example": 459 }, "partition_bytes": { "type": "integer", "example": 84846157 }, "chunk_size": { "type": "integer", "example": 5000 }, "state_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "permit_status_code_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "permit_status_desc_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "permit_type_desc_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "component_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "current_violation_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "cwa_status_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "major_minor_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "query_policy": { "type": "object", "additionalProperties": { "type": "string" } }, "settlement_policy": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EpaEchoNpdesOutfallRecord": { "type": "object", "required": [ "schema_id", "record_id", "source_id", "source_record_id", "source_snapshot_id", "source_uri", "source_official_url", "source_page_url", "normalization_version", "facility", "permit", "compliance", "industry", "outfall", "location", "quality_flags", "published_at" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_outfall.v1" }, "record_id": { "type": "string", "example": "epa_echo_npdes_outfalls_layer:TX:GM0000009:1" }, "source_id": { "type": "string", "example": "epa_echo_npdes_outfalls_layer" }, "source_record_id": { "type": "string" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "normalization_version": { "type": "string" }, "facility": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "location_address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state_code": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "county_name": { "type": [ "string", "null" ] }, "facility_type_code": { "type": [ "string", "null" ] }, "facility_type_desc": { "type": [ "string", "null" ] }, "federal_agency_name": { "type": [ "string", "null" ] }, "indian_spatial_flag": { "type": [ "boolean", "null" ] }, "derived_tribes": { "type": "array", "items": { "type": "string" } } } }, "permit": { "type": "object", "properties": { "external_permit_number": { "type": [ "string", "null" ] }, "permit_name": { "type": [ "string", "null" ] }, "permit_type_code": { "type": [ "string", "null" ] }, "permit_type_desc": { "type": [ "string", "null" ] }, "permit_status_code": { "type": [ "string", "null" ] }, "permit_status_desc": { "type": [ "string", "null" ] }, "permit_components": { "type": "array", "items": { "type": "string" } }, "effective_date": { "type": [ "string", "null" ] }, "expiration_date": { "type": [ "string", "null" ] }, "termination_date": { "type": [ "string", "null" ] }, "major_minor_flag": { "type": [ "string", "null" ] }, "total_design_flow_mgd": { "type": [ "number", "null" ] } } }, "compliance": { "type": "object", "properties": { "current_snc_status": { "type": [ "string", "null" ] }, "current_violation": { "type": [ "boolean", "null" ] }, "cwa_current_status": { "type": [ "string", "null" ] }, "date_last_inspection": { "type": [ "string", "null" ] }, "date_last_formal_enforcement_action": { "type": [ "string", "null" ] }, "dmr_pounds": { "type": [ "number", "null" ] }, "limit_pollutant": { "type": [ "string", "null" ] } } }, "industry": { "type": "object", "properties": { "sic_codes": { "type": "array", "items": { "type": "string" } }, "sic_descriptions": { "type": "array", "items": { "type": "string" } }, "naics_codes": { "type": "array", "items": { "type": "string" } } } }, "outfall": { "type": "object", "properties": { "permit_feature_number": { "type": [ "string", "null" ] }, "state_water_body_name": { "type": [ "string", "null" ] }, "subtype_desc": { "type": [ "string", "null" ] }, "latlong_type": { "type": [ "string", "null" ] } } }, "location": { "type": "object", "properties": { "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } }, "quality_flags": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "format": "date-time" } } }, "EpaEchoNpdesOutfallResponse": { "type": "object", "required": [ "schema_id", "asset_id", "source_id", "data_snapshot_id", "record_count", "filters", "manifest", "partitions", "records", "access", "_links" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_outfall.v1" }, "asset_id": { "type": "string", "example": "context.epa_echo_npdes_outfalls" }, "source_id": { "type": "string", "example": "epa_echo_npdes_outfalls_layer" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": true }, "manifest": { "$ref": "#/components/schemas/EpaEchoNpdesOutfallManifestSummary" }, "partitions": { "type": "array", "items": { "$ref": "#/components/schemas/EpaEchoNpdesOutfallPartition" } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/EpaEchoNpdesOutfallRecord" } }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EpaEchoNpdesSewerOverflowHistoryManifestSummary": { "type": "object", "required": [ "schema_id", "generated_at", "run_id", "source_id", "source_official_url", "source_page_url", "source_snapshot_id", "source_uri", "normalized_prefix_uri", "event_payload_uri", "event_payload_public_path", "event_payload_bytes", "table_counts", "event_count", "current_event_count", "replaced_event_count", "permit_count", "events_with_coordinates", "events_with_volume", "reported_volume_gallons_sum", "state_counts", "current_state_counts", "event_type_counts", "structure_type_counts", "settlement_policy" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_sewer_overflow_history_manifest.v1" }, "generated_at": { "type": "string", "format": "date-time" }, "run_id": { "type": "string", "example": "20260718T200643+0000" }, "source_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_history" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "normalized_prefix_uri": { "type": "string" }, "event_payload_uri": { "type": "string" }, "event_payload_public_path": { "type": "string" }, "event_payload_bytes": { "type": "integer", "example": 24299652 }, "table_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "event_count": { "type": "integer", "example": 5480 }, "permit_count": { "type": "integer", "example": 639 }, "events_with_coordinates": { "type": "integer", "example": 3768 }, "events_with_volume": { "type": "integer", "example": 4081 }, "reported_volume_gallons_sum": { "type": "number", "example": 15097207815 }, "state_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "event_type_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "structure_type_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "settlement_policy": { "type": "object", "additionalProperties": { "type": "string" } }, "current_event_count": { "type": "integer", "example": 4685 }, "replaced_event_count": { "type": "integer", "example": 795 }, "current_state_counts": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "EpaEchoNpdesSewerOverflowHistoryRecord": { "type": "object", "required": [ "schema_id", "record_id", "source_id", "source_record_id", "source_snapshot_id", "source_uri", "source_official_url", "source_page_url", "normalization_version", "permit", "report", "event", "location", "related", "quality_flags", "published_at" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_sewer_overflow_history_event.v1" }, "record_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_history:IL0029449:4199:303117009" }, "source_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_history" }, "source_record_id": { "type": "string" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "normalization_version": { "type": "string" }, "permit": { "type": "object", "properties": { "permit_id": { "type": [ "string", "null" ] }, "state_code": { "type": [ "string", "null" ] }, "collection_system_identifier": { "type": [ "string", "null" ] }, "permitted_feature_identifier": { "type": [ "string", "null" ] }, "collection_system": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "owner_type_code": { "type": [ "string", "null" ] }, "owner_type_desc": { "type": [ "string", "null" ] }, "population": { "type": [ "number", "null" ] }, "percent_combined_sewer_system": { "type": [ "number", "null" ] } } } } }, "report": { "type": "object", "properties": { "program_report_form_set_id": { "type": [ "string", "null" ] }, "program_report_form_id": { "type": [ "string", "null" ] }, "event_id_external": { "type": [ "string", "null" ] }, "received_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "end_date": { "type": [ "string", "null" ] }, "payload_id": { "type": [ "string", "null" ] }, "transaction_type": { "type": [ "string", "null" ] }, "event_transaction_type": { "type": [ "string", "null" ] }, "electronic_submission_type_code": { "type": [ "string", "null" ] }, "electronic_submission_type_desc": { "type": [ "string", "null" ] }, "transaction_id": { "type": [ "string", "null" ] }, "current_report_form_flag": { "type": [ "boolean", "null" ] }, "replaced_date": { "type": [ "string", "null" ] }, "replacing_payload_id": { "type": [ "string", "null" ] }, "npdes_data_group_number_code": { "type": [ "string", "null" ] } } }, "event": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "reporting_requirement_code": { "type": [ "string", "null" ] }, "reporting_requirement_desc": { "type": [ "string", "null" ] }, "wet_weather": { "type": [ "boolean", "null" ] }, "structure_type_code": { "type": [ "string", "null" ] }, "structure_type_desc": { "type": [ "string", "null" ] }, "structure_type_other_text": { "type": [ "string", "null" ] }, "duration_hours": { "type": [ "number", "null" ] }, "start_datetime": { "type": [ "string", "null" ] }, "end_datetime": { "type": [ "string", "null" ] }, "discharge_quantification_method_code": { "type": [ "string", "null" ] }, "discharge_quantification_method_desc": { "type": [ "string", "null" ] }, "discharge_volume_gallons": { "type": [ "number", "null" ] }, "discharge_rate_gph": { "type": [ "number", "null" ] }, "anticipated_bypass_text": { "type": [ "string", "null" ] }, "anticipated_bypass_expect_limit_violation": { "type": [ "boolean", "null" ] }, "anticipated_bypass_expect_limit_violation_text": { "type": [ "string", "null" ] } } }, "location": { "type": "object", "properties": { "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } }, "related": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "causes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "impacts": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "corrective_actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "receiving_waters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "treatment_codes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "quality_flags": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "format": "date-time" } } }, "EpaEchoNpdesSewerOverflowHistoryResponse": { "type": "object", "required": [ "schema_id", "asset_id", "source_id", "data_snapshot_id", "record_count", "filters", "manifest", "records", "access", "_links" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_sewer_overflow_history_event.v1" }, "asset_id": { "type": "string", "example": "context.epa_echo_npdes_sewer_overflow_history" }, "source_id": { "type": "string", "example": "epa_echo_npdes_sewer_overflow_history" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": true }, "manifest": { "$ref": "#/components/schemas/EpaEchoNpdesSewerOverflowHistoryManifestSummary" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/EpaEchoNpdesSewerOverflowHistoryRecord" } }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EpaEchoNpdesViolationPartition": { "type": "object", "required": [ "state_code", "category", "record_count", "public_path", "uri", "bytes", "uncompressed_bytes", "content_encoding" ], "properties": { "state_code": { "type": "string", "example": "TX" }, "category": { "type": "string", "enum": [ "permit_schedule", "compliance_schedule", "single_event" ], "example": "single_event" }, "record_count": { "type": "integer", "example": 5000 }, "public_path": { "type": "string" }, "public_url": { "type": "string", "format": "uri" }, "uri": { "type": "string" }, "bytes": { "type": "integer", "example": 257535 }, "uncompressed_bytes": { "type": "integer", "example": 7738672 }, "content_encoding": { "type": "string", "example": "gzip" } } }, "EpaEchoNpdesViolationManifestSummary": { "type": "object", "required": [ "schema_id", "generated_at", "run_id", "source_id", "source_official_url", "source_page_url", "source_snapshot_id", "source_uri", "normalized_prefix_uri", "source_members", "source_object", "record_count", "partition_count", "partition_payload_bytes", "state_counts", "category_counts", "violation_type_counts", "violation_code_counts", "rnc_detection_counts", "rnc_resolution_counts", "enforcement_link_count", "records_with_linked_enforcement", "enforcement_activity_type_counts", "enforcement_violation_code_counts", "settlement_policy" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_violation_manifest.v1" }, "generated_at": { "type": "string", "format": "date-time" }, "run_id": { "type": "string", "example": "20260718T204822+0000" }, "source_id": { "type": "string", "example": "epa_echo_npdes_violations" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "normalized_prefix_uri": { "type": "string" }, "source_members": { "type": "object", "additionalProperties": true }, "source_object": { "type": "object", "additionalProperties": true }, "record_count": { "type": "integer", "example": 782170 }, "partition_count": { "type": "integer", "example": 286 }, "partition_payload_bytes": { "type": "integer", "example": 40549489 }, "state_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "category_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "violation_type_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "violation_code_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "rnc_detection_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "rnc_resolution_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "enforcement_link_count": { "type": "integer", "example": 4928870 }, "records_with_linked_enforcement": { "type": "integer", "example": 155949 }, "enforcement_activity_type_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "enforcement_violation_code_counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "settlement_policy": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EpaEchoNpdesViolationRecord": { "type": "object", "required": [ "schema_id", "record_id", "source_id", "source_record_id", "source_snapshot_id", "source_uri", "source_official_url", "source_page_url", "normalization_version", "permit", "violation", "schedule", "dates", "rnc", "enforcement", "quality_flags", "published_at" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_violation.v1" }, "record_id": { "type": "string", "example": "epa_echo_npdes_violations:TX:single_event:TX0020478:12345" }, "source_id": { "type": "string", "example": "epa_echo_npdes_violations" }, "source_record_id": { "type": "string" }, "source_snapshot_id": { "type": "string" }, "source_uri": { "type": "string" }, "source_official_url": { "type": "string", "format": "uri" }, "source_page_url": { "type": "string", "format": "uri" }, "normalization_version": { "type": "string" }, "permit": { "type": "object", "properties": { "permit_id": { "type": [ "string", "null" ] }, "state_code": { "type": [ "string", "null" ] } } }, "violation": { "type": "object", "properties": { "violation_id": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "permit_schedule", "compliance_schedule", "single_event" ] }, "type_code": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "single_event_comment": { "type": [ "string", "null" ] }, "single_event_agency_type_code": { "type": [ "string", "null" ] } } }, "schedule": { "type": "object", "properties": { "permit_schedule_event_id": { "type": [ "string", "null" ] }, "compliance_schedule_event_id": { "type": [ "string", "null" ] }, "compliance_schedule_number": { "type": [ "string", "null" ] }, "event_code": { "type": [ "string", "null" ] }, "event_description": { "type": [ "string", "null" ] } } }, "dates": { "type": "object", "properties": { "schedule_date": { "type": [ "string", "null" ] }, "actual_date": { "type": [ "string", "null" ] }, "report_received_date": { "type": [ "string", "null" ] }, "single_event_violation_date": { "type": [ "string", "null" ] }, "single_event_end_date": { "type": [ "string", "null" ] }, "rnc_detection_date": { "type": [ "string", "null" ] }, "rnc_resolution_date": { "type": [ "string", "null" ] } } }, "rnc": { "type": "object", "properties": { "detection_code": { "type": [ "string", "null" ] }, "detection_description": { "type": [ "string", "null" ] }, "resolution_code": { "type": [ "string", "null" ] }, "resolution_description": { "type": [ "string", "null" ] } } }, "enforcement": { "type": "object", "properties": { "linked_action_count": { "type": "integer", "example": 1 } } }, "quality_flags": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": "string", "format": "date-time" } } }, "EpaEchoNpdesViolationResponse": { "type": "object", "required": [ "schema_id", "asset_id", "source_id", "data_snapshot_id", "record_count", "filters", "manifest", "partitions", "records", "access", "_links" ], "properties": { "schema_id": { "type": "string", "example": "hc.epa_echo_npdes_violation.v1" }, "asset_id": { "type": "string", "example": "context.epa_echo_npdes_violations" }, "source_id": { "type": "string", "example": "epa_echo_npdes_violations" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object", "additionalProperties": true }, "manifest": { "$ref": "#/components/schemas/EpaEchoNpdesViolationManifestSummary" }, "partitions": { "type": "array", "items": { "$ref": "#/components/schemas/EpaEchoNpdesViolationPartition" } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/EpaEchoNpdesViolationRecord" } }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "paths": { "/api/v1/forecast": { "get": { "operationId": "forecastByAddress", "summary": "Forecast by street address", "description": "Geocodes a US address to an H3 cell and returns probabilistic value forecasts. Best coverage: Houston metro. Returns P10/P50/P90 and a 5-year fan chart.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string" }, "example": "5000 Westheimer Rd Houston TX 77056" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2026, "maximum": 2030, "default": 2030 } } ], "responses": { "200": { "description": "Forecast data", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No forecast for address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded (demo tier)" } } } }, "/api/v1/forecast/lot": { "get": { "operationId": "forecastByParcel", "summary": "Forecast by tax parcel", "description": "Lot-level probabilistic forecasts by county assessor account number. Coverage: Florida statewide + Houston metro.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "acct", "in": "query", "required": true, "schema": { "type": "string" }, "description": "County tax parcel account number.", "example": "00404328020003500" } ], "responses": { "200": { "description": "Parcel forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/unit": { "get": { "operationId": "forecastByUnit", "summary": "Forecast by condo/unit", "description": "Individual unit-level forecasts. Optionally returns all sibling units in the same condo building. Coverage: Florida statewide + Houston metro.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "acct", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "include_siblings", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Unit forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/tabblock": { "get": { "operationId": "forecastByTabblock", "summary": "Forecast by Census tabulation block", "description": "Sub-neighborhood probabilistic forecasts. 15-digit GEOID20. Coverage: NYC (32K tabblocks) + Houston metro (34K tabblocks).", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "geoid", "in": "query", "required": true, "schema": { "type": "string", "minLength": 15, "maxLength": 15 }, "example": "360050002000001" } ], "responses": { "200": { "description": "Tabblock forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/tract": { "get": { "operationId": "forecastByTract", "summary": "Forecast by Census tract", "description": "Neighborhood-level probabilistic forecasts. 11-digit GEOID20. Coverage: FL + Houston via jurisdiction model; all ~82K US tracts via ACS nationwide model.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "geoid", "in": "query", "required": true, "schema": { "type": "string", "minLength": 11, "maxLength": 11 }, "example": "48201231400" } ], "responses": { "200": { "description": "Tract forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/zcta": { "get": { "operationId": "forecastByZcta", "summary": "Forecast by ZIP code (ZCTA)", "description": "ZIP-level probabilistic forecasts. ~20,000 ZCTAs nationwide with 6-year horizon.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "zcta", "in": "query", "required": true, "schema": { "type": "string", "minLength": 5, "maxLength": 5 }, "example": "77056" } ], "responses": { "200": { "description": "ZCTA forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/zip3": { "get": { "operationId": "forecastByZip3", "summary": "Forecast by ZIP3", "description": "ZIP3-level forecasts (first 3 digits of ZIP code). 6,210 areas nationwide.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "zip3", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 3 }, "example": "770" } ], "responses": { "200": { "description": "ZIP3 forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/county": { "get": { "operationId": "forecastByCounty", "summary": "Forecast by county", "description": "County-level probabilistic forecasts. Nationwide coverage. Returns P10/P25/P50/P75/P90 fan chart with growth % and growth $ fields.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "fips", "in": "query", "required": true, "schema": { "type": "string", "minLength": 5, "maxLength": 5 }, "example": "48201", "description": "5-digit county FIPS (state 2 + county 3)." } ], "responses": { "200": { "description": "County forecast", "content": { "application/json": { "schema": { "type": "object", "properties": { "fips": { "type": "string" }, "level": { "type": "string", "enum": [ "county" ] }, "origin_year": { "type": "integer" }, "current_value": { "type": [ "integer", "null" ] }, "fan_chart": { "type": "array", "items": { "$ref": "#/components/schemas/FanChartPoint" } }, "_links": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/state": { "get": { "operationId": "forecastByState", "summary": "Forecast by state", "description": "State-level probabilistic forecasts. All 50 US states covered.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "fips", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": "48", "description": "2-digit state FIPS. TX=48, FL=12, NY=36, CA=06." } ], "responses": { "200": { "description": "State forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/forecast/hex": { "get": { "operationId": "forecastByH3Cell", "summary": "Forecast by H3 hex cell (legacy)", "description": "Neighborhood-level forecasts by H3 cell ID at resolution 8. Houston metro only. Prefer forecast/tabblock or forecast/tract for new integrations.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "h3_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "882a100c65fffff" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "H3 forecast", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/outlook/county": { "get": { "operationId": "getCountyOutlook", "summary": "County outlook metrics", "description": "Pre-computed county outlook: median appreciation, highest-upside estimate, median home value, and a value trajectory array. Updated weekly.", "security": [], "tags": [ "Forecasts" ], "parameters": [ { "name": "fips", "in": "query", "required": true, "schema": { "type": "string", "minLength": 5, "maxLength": 5 }, "example": "48201" } ], "responses": { "200": { "description": "County outlook", "content": { "application/json": { "schema": { "type": "object", "properties": { "fips": { "type": "string" }, "median_appreciation": { "type": [ "number", "null" ] }, "highest_upside": { "type": [ "number", "null" ] }, "median_value": { "type": [ "integer", "null" ] }, "trajectory": { "type": [ "array", "null" ], "items": { "type": "number" } }, "last_updated": { "type": [ "string", "null" ], "format": "date-time" }, "_links": { "type": "object" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/benchmarks/catalog": { "get": { "operationId": "listBenchmarkDatasets", "summary": "List benchmark and public-data assets", "description": "Catalog of public-safe benchmark and public-data assets, including release phase, support level, benchmark role, and recommended surface.", "security": [], "tags": [ "Benchmarks" ], "parameters": [ { "name": "asset_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "backtest.public_vintage_oeo_maricopa_2022" }, { "name": "asset_class", "in": "query", "required": false, "schema": { "type": "string" }, "example": "backtest_vintage_outputs" }, { "name": "phase", "in": "query", "required": false, "schema": { "type": "string" }, "example": "phase_1" }, { "name": "public_readiness", "in": "query", "required": false, "schema": { "type": "string" }, "example": "launch" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] }, "example": "json" } ], "responses": { "200": { "description": "Benchmark catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "dataset_count": { "type": "integer" }, "launch_ready_count": { "type": "integer" }, "filters": { "type": "object" }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkCatalogEntry" } }, "_links": { "type": "object" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown asset_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/benchmarks/vintages": { "get": { "operationId": "getBenchmarkVintages", "summary": "Retrieve validated public forecast vintages", "description": "Validated public-vintage rows with provenance-heavy fields such as vintage_id, publication_date, support_level, benchmark_role, and license_note.", "security": [], "tags": [ "Benchmarks" ], "parameters": [ { "name": "vintage_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "az_oeo_maricopa_medium_2022_report" }, { "name": "support_level", "in": "query", "required": false, "schema": { "type": "string" }, "example": "county" }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "example": "total_population" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] }, "example": "json" } ], "responses": { "200": { "description": "Public forecast vintage rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "vintage_count": { "type": "integer" }, "row_count": { "type": "integer" }, "filters": { "type": "object" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/PublicForecastVintageRecord" } }, "_links": { "type": "object" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown vintage_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/benchmarks/backtests": { "get": { "operationId": "getBenchmarkBacktests", "summary": "Retrieve public-safe benchmark score tables", "description": "Public-safe benchmark score summaries such as model-vs-persistence tables. Payloads carry asset IDs, artifact IDs, model version labels, and per-target score rows.", "security": [], "tags": [ "Benchmarks" ], "parameters": [ { "name": "benchmark_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "acs_cutoff2016_horizon8_maricopa_realized_acs" }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "example": "total_population" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] }, "example": "json" } ], "responses": { "200": { "description": "Benchmark score tables", "content": { "application/json": { "schema": { "type": "object", "properties": { "benchmark_count": { "type": "integer" }, "filters": { "type": "object" }, "benchmarks": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkBacktestResult" } }, "_links": { "type": "object" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown benchmark_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/benchmarks/sources": { "get": { "operationId": "getBenchmarkSources", "summary": "Retrieve provenance manifests and source catalogs", "description": "Source catalogs, archive ledgers, and benchmark registry metadata with provenance-heavy fields. Use include_details=true to expand nested source lists.", "security": [], "tags": [ "Benchmarks" ], "parameters": [ { "name": "asset_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "provenance.arizona_archive_status_ledger" }, { "name": "include_details", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] }, "example": "json" } ], "responses": { "200": { "description": "Benchmark source manifests", "content": { "application/json": { "schema": { "type": "object", "properties": { "manifest_count": { "type": "integer" }, "filters": { "type": "object" }, "manifests": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkSourceManifest" } }, "_links": { "type": "object" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown asset_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/catalog": { "get": { "operationId": "listDataAssets", "summary": "List canonical data assets", "description": "Matrix-backed canonical data-asset catalog spanning public, metadata-only, restricted, and unavailable Homecastr data surfaces.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "asset_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "forecast.tract_home_value" }, { "name": "data_family", "in": "query", "required": false, "schema": { "type": "string" }, "example": "forecast_output" }, { "name": "public_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "launch" }, { "name": "visibility", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "public", "metadata_only", "restricted", "unavailable" ] }, "example": "public" }, { "name": "inventory_asset", "in": "query", "required": false, "schema": { "type": "string" }, "example": "forecast.aggregate_surfaces" } ], "responses": { "200": { "description": "Canonical data asset catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "family_count": { "type": "integer" }, "filters": { "type": "object" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataAssetRecord" } }, "page": { "type": "object" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "404": { "description": "Unknown asset_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/assets/{asset_id}": { "get": { "operationId": "getDataAsset", "summary": "Get canonical data asset detail", "description": "Returns one canonical data-asset record, including current and target surfaces, contracts, provenance, access policy, and related artifacts.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "asset_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "context.census_acs" } ], "responses": { "200": { "description": "Canonical data asset detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record": { "$ref": "#/components/schemas/DataAssetRecord" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "404": { "description": "Unknown asset_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/sources": { "get": { "operationId": "listDataSources", "summary": "List original data sources", "description": "Source-level catalog for upstream feeds used, staged, or reviewed for Homecastr panels. Returns official outbound source URLs, public-readiness labels, license status, and panel links without mirroring governed raw payloads.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "source.hcad_houston.assessor", "description": "Optional exact source identifier." }, { "name": "data_family", "in": "query", "required": false, "schema": { "type": "string" }, "example": "assessor_tax", "description": "Alias for source_family for compatibility with existing clients." }, { "name": "source_family", "in": "query", "required": false, "schema": { "type": "string" }, "example": "assessor_tax", "description": "Optional upstream source-family filter." }, { "name": "source_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "used", "description": "Optional source status such as used, candidate, blocked, or mentioned." }, { "name": "public_readiness", "in": "query", "required": false, "schema": { "type": "string" }, "example": "metadata_public", "description": "Optional public-readiness filter." }, { "name": "license_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "public_source_metadata_only", "description": "Optional license or policy status filter." }, { "name": "panel_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "panel.acs_nationwide", "description": "Optional canonical panel identifier." } ], "responses": { "200": { "description": "Original source inventory", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string", "example": "hc.source_inventory.v1" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataSourceRecord" } }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } } } } }, "/api/v1/data/schemas": { "get": { "operationId": "listDataSchemas", "summary": "List canonical schema contracts", "description": "Schema-bundle catalog for canonical dataset, panel, forecast, benchmark, provenance, and artifact contracts.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "schema_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "hc.dataset_asset.v1" }, { "name": "data_family", "in": "query", "required": false, "schema": { "type": "string" }, "example": "forecast_output" } ], "responses": { "200": { "description": "Canonical schema catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "filters": { "type": "object" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataSchemaRecord" } }, "page": { "type": "object" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "404": { "description": "Unknown schema_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/schemas/{schema_id}": { "get": { "operationId": "getDataSchema", "summary": "Get canonical schema detail", "description": "Returns one canonical schema definition together with the data families and assets that reference it.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "schema_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "hc.panel_row.v1" } ], "responses": { "200": { "description": "Canonical schema detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record": { "$ref": "#/components/schemas/DataSchemaDetail" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "404": { "description": "Unknown schema_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/vintages/{vintage_id}": { "get": { "operationId": "getForecastVintage", "summary": "Get canonical forecast vintage", "description": "Returns one canonical public forecast vintage grouped into standardized same-vintage forecast series for benchmark consumers.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "vintage_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "az_oeo_maricopa_medium_2022_report" }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "example": "total_population" } ], "responses": { "200": { "description": "Canonical forecast vintage", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "vintage_id": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "filters": { "type": "object" }, "record_count": { "type": "integer" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/CanonicalForecastVintageRecord" } }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "400": { "description": "Invalid vintage query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown or empty vintage_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/benchmarks/{benchmark_id}": { "get": { "operationId": "getBenchmarkResult", "summary": "Get canonical benchmark result", "description": "Returns one canonical benchmark result with standardized score rows, reproducibility references, and benchmark-only labeling.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "benchmark_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "acs_cutoff2016_horizon8_maricopa_realized_acs" }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "example": "total_population" } ], "responses": { "200": { "description": "Canonical benchmark result", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "benchmark_id": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "filters": { "type": "object" }, "score_count": { "type": "integer" }, "record": { "$ref": "#/components/schemas/CanonicalBenchmarkResultRecord" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "400": { "description": "Invalid benchmark query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown or empty benchmark_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/provenance/{provenance_id}": { "get": { "operationId": "getProvenance", "summary": "Get canonical provenance detail", "description": "Returns one reviewed provenance manifest or source ledger with publication, retrieval, benchmark-role, and summary metadata.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "provenance_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "provenance.arizona_archive_status_ledger" } ], "responses": { "200": { "description": "Canonical provenance detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record": { "$ref": "#/components/schemas/DataProvenanceRecord" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "404": { "description": "Unknown provenance_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/artifacts/{artifact_id}": { "get": { "operationId": "getDataArtifact", "summary": "Get artifact manifest metadata", "description": "Returns one reviewed public artifact manifest, including format, owner asset, retrieval metadata, and canonical download path.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "public-data.full_data_surface_matrix_tsv" } ], "responses": { "200": { "description": "Artifact manifest detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record": { "$ref": "#/components/schemas/DataArtifactManifest" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "404": { "description": "Unknown artifact_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/artifacts/{artifact_id}/download": { "get": { "operationId": "downloadDataArtifact", "summary": "Download a reviewed public artifact", "description": "Downloads the current reviewed artifact bytes for a canonical artifact_id. Media type depends on the artifact format.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "artifact_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "public-data.full_data_surface_matrix_tsv" } ], "responses": { "200": { "description": "Artifact download", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Unknown artifact_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/training-runs": { "get": { "operationId": "listTrainingRuns", "summary": "ML training run history", "description": "Lists ML model training runs with jurisdiction, instance type, duration, and compute cost. Requires a non-demo API key.", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "Internal" ], "parameters": [ { "name": "jurisdiction", "in": "query", "required": false, "schema": { "type": "string" }, "example": "hcad_houston" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer" }, "example": 2024 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Training runs list", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "filters": { "type": "object" }, "runs": { "type": "array", "items": { "type": "object" } }, "_links": { "type": "object" } } } } } }, "401": { "description": "API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/analytics/events": { "get": { "operationId": "getAnalyticsEvents", "summary": "Product event analytics", "description": "Aggregated product event counts and recent raw events (PII stripped). Requires a non-demo API key.", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "Internal" ], "parameters": [ { "name": "event_name", "in": "query", "required": false, "schema": { "type": "string" }, "example": "map_viewport_load" }, { "name": "page_path", "in": "query", "required": false, "schema": { "type": "string" }, "example": "/map" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 7 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } } ], "responses": { "200": { "description": "Event stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer" }, "since": { "type": "string", "format": "date-time" }, "filters": { "type": "object" }, "summary": { "type": "array", "items": { "type": "object" } }, "events": { "type": "array", "items": { "type": "object" } }, "_links": { "type": "object" } } } } } }, "401": { "description": "API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data-readiness/permits-zoning": { "get": { "operationId": "getPermitZoningReadiness", "summary": "Permit and zoning data readiness", "description": "Returns source-level permit, zoning, energy, and public-record readiness metadata: verified R2 evidence, acquisition gaps, market template gates, and API/MCP exposure status. This endpoint does not expose raw permit or zoning rows.", "security": [], "tags": [ "Data Readiness" ], "parameters": [ { "name": "summary", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Return only aggregate source and market readiness counts." }, { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "census_bps_county_monthly_ascii", "description": "Return one source readiness record." }, { "name": "market_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "monthly_county_permit_pulse", "description": "Return one market-template readiness record." } ], "responses": { "200": { "description": "Permit and zoning readiness metadata", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown source_id or market_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/permits/census-bps/county-monthly": { "get": { "operationId": "queryCensusBpsCountyMonthly", "summary": "Query normalized Census BPS county-month permit rows", "description": "Returns public, normalized Census Building Permits Survey county-month rows from Homecastr's R2-backed permit/zoning surface. Defaults to the latest current-month partition and a capped row limit. For contract-style settlement, specify county_fips, year, month, and kind=current_month.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 2000, "maximum": 2100 }, "example": 2026, "description": "Four-digit survey year. Supply together with month unless history=true." }, { "name": "month", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 12 }, "example": 6, "description": "Survey month. Supply together with year unless history=true." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "current_month", "year_to_date" ], "default": "current_month" }, "description": "Census BPS file kind." }, { "name": "county_fips", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{5}$" }, "example": "48201", "description": "Optional 5-digit county FIPS filter." }, { "name": "state_fips", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{1,2}$" }, "example": "48", "description": "Optional state FIPS filter. Single-digit values are left-padded by the API." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Maximum rows to return." }, { "name": "history", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Return a county time series across available partitions. Requires county_fips." }, { "name": "summary", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Return manifest and partition metadata without row payloads." } ], "responses": { "200": { "description": "Normalized Census BPS county-month row response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CensusBpsCountyMonthlyResponse" } } } }, "400": { "description": "Invalid filter combination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/keys": { "post": { "operationId": "createApiKey", "summary": "Request a free API key verification link", "description": "Starts email verification for a free API key. The key is shown once only after the email link is confirmed.", "security": [], "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "attribution": { "type": "object", "properties": { "utm_source": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_campaign": { "type": "string" }, "landing_url": { "type": "string" }, "referrer": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "Verification request accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "verification_required", "verification_sent", "expires_at" ], "properties": { "email": { "type": "string", "format": "email" }, "verification_required": { "type": "boolean", "const": true }, "verification_sent": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "API key verification request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "API key verification request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "API key verification request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/status": { "get": { "operationId": "getStatus", "summary": "API health status", "description": "Returns service health and version information.", "security": [], "tags": [ "Meta" ], "responses": { "200": { "description": "Service healthy", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/usage": { "get": { "operationId": "getUsage", "summary": "API usage stats for your key", "description": "Returns usage statistics for the authenticated API key: request counts, breakdown by endpoint, source, and status. Requires a non-demo API key.", "security": [ { "ApiKeyAuth": [] } ], "tags": [ "Auth" ], "responses": { "200": { "description": "Usage stats", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/entities/{entity_id}": { "get": { "operationId": "getEntity", "summary": "Get canonical entity metadata", "description": "Returns one canonical geography entity with normalized ID namespace, parent hierarchy, labels, aliases, and source asset links.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "48201231400" }, { "name": "entity_type", "in": "query", "required": false, "schema": { "type": "string" }, "example": "tract" } ], "responses": { "200": { "description": "Canonical entity detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record": { "$ref": "#/components/schemas/DataEntityRecord" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "400": { "description": "Invalid entity lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/crosswalks": { "get": { "operationId": "getGeographyCrosswalk", "summary": "Resolve canonical geography crosswalks", "description": "Returns crosswalk rows such as tract-to-county, tract-to-state, tract-to-ZCTA, or tabblock-to-tract mappings.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "source_entity_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "48201231400" }, { "name": "source_entity_type", "in": "query", "required": false, "schema": { "type": "string" }, "example": "tract" }, { "name": "target_entity_type", "in": "query", "required": false, "schema": { "type": "string" }, "example": "zcta" } ], "responses": { "200": { "description": "Canonical crosswalk rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "filters": { "type": "object" }, "record_count": { "type": "integer" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataCrosswalkRecord" } }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "400": { "description": "Invalid crosswalk lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No crosswalk rows found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/sources/{source_id}": { "get": { "operationId": "getDataSource", "summary": "Get one original data source", "description": "Returns one upstream source record with official outbound URLs, panel links, provenance metadata, and access policy.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "source.hcad_houston.assessor" } ], "responses": { "200": { "description": "Original source record", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string", "example": "hc.source_inventory.v1" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record": { "$ref": "#/components/schemas/DataSourceRecord" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } }, "404": { "description": "Unknown source_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/data/panels/{panel_id}/lineage": { "get": { "operationId": "getPanelLineage", "summary": "Get panel source lineage", "description": "Returns source-to-panel lineage edges for a canonical panel, including source roles, join keys, transforms, output fields, and official upstream source links.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "panel_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "panel.acs_nationwide" }, { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "census.acs.tract_5yr", "description": "Optional exact source identifier." } ], "responses": { "200": { "description": "Panel lineage records", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string", "example": "hc.panel_lineage.v1" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "panel_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataPanelLineageRecord" } }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } } } } }, "/api/v1/data/coverage": { "get": { "operationId": "getDataCoverage", "summary": "Summarize source and panel coverage", "description": "Returns aggregate counts and panel/source breakdowns used by the public docs visuals and source-coverage audits.", "security": [], "tags": [ "Data" ], "parameters": [], "responses": { "200": { "description": "Source and panel coverage summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string", "example": "hc.data_coverage_summary.v1" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "coverage": { "$ref": "#/components/schemas/DataCoverageSummary" }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } } } } }, "/api/v1/data/coverage/map": { "get": { "operationId": "getSourceCoverageMap", "summary": "Get source coverage map GeoJSON", "description": "Returns the declared source-coverage GeoJSON layer used by the interactive docs map. Features associate public reference boundaries or generalized selection regions with source IDs, source names, official upstream URLs, panel links, readiness, license metadata, and geometry notes. The layer does not redistribute source-native parcel, permit, assessor, utility, building, zoning, or hazard geometry.", "security": [], "tags": [ "Data" ], "parameters": [], "responses": { "200": { "description": "Source coverage GeoJSON FeatureCollection", "content": { "application/geo+json": { "schema": { "$ref": "#/components/schemas/SourceCoverageMap" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SourceCoverageMap" } } } } } } }, "/api/v1/data/coverage/sources": { "get": { "operationId": "listSourceCoverageIndex", "summary": "List source-to-coverage geography index rows", "description": "Returns one row per source linking source inventory records to coverage-map feature IDs, declared geography tokens, panels, official upstream URLs, native-boundary review status, and the geometry redistribution policy. This is the machine-readable counterpart to the interactive coverage atlas; it does not redistribute source-native boundary payloads.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "az.maricopa_parcels", "description": "Optional exact source identifier." }, { "name": "coverage_feature_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "coverage.arizona_phoenix_maricopa_pinal", "description": "Optional coverage-map feature or region identifier." }, { "name": "region_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "coverage.arizona_phoenix_maricopa_pinal", "description": "Alias for coverage_feature_id." }, { "name": "panel_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "panel.az_maricopa_mag_multires_enriched", "description": "Optional canonical panel identifier." }, { "name": "source_family", "in": "query", "required": false, "schema": { "type": "string" }, "example": "maricopa_assessor_parcels", "description": "Optional source-family filter." }, { "name": "coverage_geometry_role", "in": "query", "required": false, "schema": { "type": "string" }, "example": "reference_boundary", "description": "Optional coverage geometry role filter: reference_boundary or generalized_selection_region." }, { "name": "geometry_role", "in": "query", "required": false, "schema": { "type": "string" }, "example": "reference_boundary", "description": "Alias for coverage_geometry_role." }, { "name": "native_boundary_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "native_boundary_candidate_terms_review_required", "description": "Optional native-boundary review status filter." }, { "name": "public_readiness", "in": "query", "required": false, "schema": { "type": "string" }, "example": "metadata_public", "description": "Optional public-readiness filter." }, { "name": "license_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "public_source_metadata_only", "description": "Optional license or policy status filter." } ], "responses": { "200": { "description": "Source coverage index records", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string", "example": "hc.source_coverage_index.v1" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataSourceCoverageRecord" } }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } } } } }, "/api/v1/data/acquisition/public-records": { "get": { "operationId": "listPublicRecordsAcquisition", "summary": "List public-records acquisition evidence lanes", "description": "Returns metadata-only public-records acquisition and public-route evidence rows folded in from source-review work. Rows document durable cloud evidence, public-route checks, records-law gate posture, holdbacks, and next safe action without publishing protected correspondence, source-native raw payloads, or send-ready request copy.", "security": [], "tags": [ "Data" ], "parameters": [ { "name": "lane_id", "in": "query", "required": false, "schema": { "type": "string" }, "example": "georgia_permit_public_routes", "description": "Optional exact acquisition lane identifier." }, { "name": "source_family", "in": "query", "required": false, "schema": { "type": "string" }, "example": "utility_energy_infrastructure", "description": "Optional source-family filter." }, { "name": "data_family", "in": "query", "required": false, "schema": { "type": "string" }, "example": "utility_energy_infrastructure", "description": "Alias for source_family." }, { "name": "geography", "in": "query", "required": false, "schema": { "type": "string" }, "example": "US-FL-Orange", "description": "Optional geography token filter." }, { "name": "current_status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "public_r2_partial_downstream_screen_complete", "description": "Optional acquisition status filter." }, { "name": "records_law_gate", "in": "query", "required": false, "schema": { "type": "string" }, "example": "closed_no_send_ready_candidate", "description": "Optional records-law or request-gate posture filter." } ], "responses": { "200": { "description": "Public-records acquisition evidence rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_id": { "type": "string", "example": "hc.public_records_acquisition.v1" }, "schema_version": { "type": "string" }, "data_snapshot_id": { "type": "string" }, "record_count": { "type": "integer" }, "filters": { "type": "object" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/PublicRecordsAcquisitionRecord" } }, "provenance": { "$ref": "#/components/schemas/DataProvenanceSummary" }, "access": { "$ref": "#/components/schemas/DataAccessSummary" }, "_links": { "type": "object" } } } } } } } } }, "/api/v1/data/permits/fast41/projects": { "get": { "tags": [ "Permit and zoning data" ], "summary": "Query normalized FAST-41 federal permitting project inventory rows", "operationId": "queryFast41Projects", "description": "Returns R2-backed FAST-41 project inventory rows with project status, sector, lead agency, state, county/city, and coordinates. This endpoint does not expose milestone-date fields; use the readiness ledger before building milestone-slippage markets.", "parameters": [ { "name": "project_id", "in": "query", "schema": { "type": "string" }, "description": "Numeric FAST-41 project id." }, { "name": "state", "in": "query", "schema": { "type": "string", "example": "TX" }, "description": "2-letter state abbreviation." }, { "name": "status", "in": "query", "schema": { "type": "string", "example": "In Progress" }, "description": "Status text filter." }, { "name": "sector", "in": "query", "schema": { "type": "string", "example": "Electricity Transmission" }, "description": "Sector text filter." }, { "name": "lead_agency", "in": "query", "schema": { "type": "string" }, "description": "Lead agency text filter." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Maximum records to return." }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Return manifest and count metadata without row payloads." } ], "responses": { "200": { "description": "FAST-41 project inventory response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fast41ProjectResponse" } } } }, "400": { "description": "Invalid query parameters." } } } }, "/api/v1/data/environmental/epa-echo/npdes-sewer-overflows": { "get": { "tags": [ "Permit and zoning data" ], "summary": "Query normalized EPA ECHO NPDES current sewer-overflow event rows", "operationId": "queryEpaEchoNpdesSewerOverflows", "description": "Returns R2-backed EPA ECHO NPDES current sewer-overflow and bypass event rows with permit, event type, timing, reported discharge volume, receiving-water, coordinate, and source-manifest context. This endpoint is public context, not an autonomous settlement oracle until refresh, checksum, late/replacement report, and resolver policies are published.", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string", "example": "IL" }, "description": "2-letter permit state prefix." }, { "name": "permit_id", "in": "query", "schema": { "type": "string", "example": "IL0029449" }, "description": "NPDES permit identifier." }, { "name": "event_type", "in": "query", "schema": { "type": "string", "example": "Sanitary Sewer Overflow" }, "description": "Event type text filter." }, { "name": "year", "in": "query", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100, "example": 2026 }, "description": "Event year from start datetime or report start date." }, { "name": "min_volume_gallons", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "Minimum reported discharge volume in gallons." }, { "name": "with_coordinates", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Require latitude and longitude." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Maximum records to return." }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Return manifest and count metadata without row payloads." } ], "responses": { "200": { "description": "EPA ECHO NPDES sewer-overflow event response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpaEchoNpdesSewerOverflowResponse" } } } }, "400": { "description": "Invalid query parameters." } } } }, "/api/v1/data/environmental/epa-echo/npdes-outfalls": { "get": { "tags": [ "Permit and zoning data" ], "summary": "Query normalized EPA ECHO ICIS-NPDES outfall rows", "operationId": "queryEpaEchoNpdesOutfalls", "description": "Returns R2-backed EPA ECHO ICIS-NPDES outfall, facility, permit-status, permit-component, waterbody, coordinate, and current-compliance context rows. This endpoint is public context, not an autonomous settlement oracle until refresh, checksum, revision-window, limits, effluent violations, detailed enforcement-action, and resolver policies are published.", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string", "example": "TX" }, "description": "2-letter permit state prefix. Required unless permit_id or summary=true is supplied." }, { "name": "permit_id", "in": "query", "schema": { "type": "string", "example": "TXR150000" }, "description": "Exact NPDES permit identifier. If state is omitted, the first two permit characters are used as the state partition." }, { "name": "status", "in": "query", "schema": { "type": "string", "example": "Effective" }, "description": "Permit status code or text filter such as 'EFF', 'Effective', 'Admin Continued', or 'Terminated'." }, { "name": "component", "in": "query", "schema": { "type": "string", "example": "Construction Stormwater" }, "description": "Permit component text filter such as Construction Stormwater, Industrial Stormwater, POTW, CSO, CAFO, or MS4." }, { "name": "current_violation", "in": "query", "schema": { "type": "boolean" }, "description": "Optional current violation flag." }, { "name": "cwa_status", "in": "query", "schema": { "type": "string", "example": "No Violation Identified" }, "description": "Clean Water Act current status text filter." }, { "name": "with_coordinates", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Require latitude and longitude." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Maximum records to return." }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Return manifest and partition metadata without row payloads." } ], "responses": { "200": { "description": "EPA ECHO ICIS-NPDES outfalls response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpaEchoNpdesOutfallResponse" } } } }, "400": { "description": "Invalid query parameters." } } } }, "/api/v1/data/environmental/epa-echo/npdes-violations": { "get": { "tags": [ "Permit and zoning data" ], "summary": "Query normalized EPA ECHO ICIS-NPDES non-effluent violation rows", "operationId": "queryEpaEchoNpdesViolations", "description": "Returns R2-backed EPA ECHO ICIS-NPDES permit-schedule, compliance-schedule, and single-event violation rows with permit, violation-code, RNC detection/resolution, linked-enforcement count, partition, and source-manifest context. This endpoint is public context, not an autonomous settlement oracle until refresh, checksum, revision-window, effluent/limits, detailed enforcement-action, and resolver policies are published.", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string", "example": "TX" }, "description": "2-letter permit state prefix. Required unless permit_id or summary=true is supplied." }, { "name": "permit_id", "in": "query", "schema": { "type": "string", "example": "TX0020478" }, "description": "Exact NPDES permit identifier. If state is omitted, the first two permit characters are used as the state partition." }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "permit_schedule", "compliance_schedule", "single_event" ], "example": "single_event" }, "description": "Violation category filter." }, { "name": "violation_code", "in": "query", "schema": { "type": "string", "example": "C40" }, "description": "ICIS violation code filter." }, { "name": "rnc_detection_code", "in": "query", "schema": { "type": "string" }, "description": "RNC detection code filter." }, { "name": "rnc_resolution_code", "in": "query", "schema": { "type": "string" }, "description": "RNC resolution code filter." }, { "name": "year", "in": "query", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100, "example": 2020 }, "description": "Calendar year based on violation, schedule, RNC detection, or actual date." }, { "name": "has_linked_enforcement", "in": "query", "schema": { "type": "boolean" }, "description": "Filter by whether a violation row has one or more linked enforcement-action rows." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Maximum records to return." }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Return manifest and partition metadata without row payloads." } ], "responses": { "200": { "description": "EPA ECHO ICIS-NPDES violations response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpaEchoNpdesViolationResponse" } } } }, "400": { "description": "Invalid query parameters." } } } }, "/api/v1/data/environmental/epa-echo/npdes-sewer-overflow-history": { "get": { "tags": [ "Permit and zoning data" ], "summary": "Query normalized EPA ECHO NPDES all-version sewer-overflow event rows", "operationId": "queryEpaEchoNpdesSewerOverflowHistory", "description": "Returns R2-backed EPA ECHO NPDES all-version sewer-overflow and bypass event rows with permit, event type, timing, reported discharge volume, current/replaced report flags, replacing payload IDs, receiving-water, coordinate, and source-manifest context. This endpoint is public context, not an autonomous settlement oracle until refresh, checksum, revision-window, and resolver policies are published.", "parameters": [ { "name": "state", "in": "query", "schema": { "type": "string", "example": "IL" }, "description": "2-letter permit state prefix." }, { "name": "permit_id", "in": "query", "schema": { "type": "string", "example": "IL0029449" }, "description": "NPDES permit identifier." }, { "name": "event_type", "in": "query", "schema": { "type": "string", "example": "Sanitary Sewer Overflow" }, "description": "Event type text filter." }, { "name": "year", "in": "query", "schema": { "type": "integer", "minimum": 1900, "maximum": 2100, "example": 2026 }, "description": "Event year from start datetime or report start date." }, { "name": "min_volume_gallons", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "Minimum reported discharge volume in gallons." }, { "name": "with_coordinates", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Require latitude and longitude." }, { "name": "current_only", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Return only rows where EPA marks the report form as current." }, { "name": "include_replaced", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "If false, exclude replaced or non-current report versions." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 100 }, "description": "Maximum records to return." }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Return manifest and count metadata without row payloads." } ], "responses": { "200": { "description": "EPA ECHO NPDES sewer-overflow event history response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpaEchoNpdesSewerOverflowHistoryResponse" } } } }, "400": { "description": "Invalid query parameters." } } } } }, "tags": [ { "name": "Scenes", "description": "Versioned possible-futures scene manifests and retained concrete realizations" }, { "name": "Forecasts", "description": "Probabilistic home value forecasts at every geographic level" }, { "name": "Benchmarks", "description": "Public benchmark catalogs, forecast vintages, score tables, and provenance manifests" }, { "name": "Data", "description": "Canonical discovery surfaces for data assets, schemas, provenance, and reviewed artifacts" }, { "name": "Data Readiness", "description": "Source readiness metadata for permit, zoning, and settlement-style workflows" }, { "name": "Content", "description": "Published county outlook metrics." }, { "name": "Auth", "description": "API key management and usage tracking" }, { "name": "Internal", "description": "Internal analytics and ML training data (non-demo API key required)" }, { "name": "Meta", "description": "API health and metadata" } ] }