{"openapi":"3.1.0","info":{"title":"HIFLD Next public webapp API","version":"1.0.0","description":"TanStack webapp JSON routes that proxy dataset-api. Start with GET /api or GET /llms.txt, then GET /api/openapi for the full contract. Not OGC API-Features or STAC: no /items or /features collections; dataset URLs use string slugs (not /datasets/3418). Search and pagination: only on GET /api/collections/{slug} using search, query, tag_filters, limit, offset, omit (not ?q= on other paths). Collection dataset listing defaults to limit=50 when omitted (breaking vs older unbounded responses). GET /api/datasets returns at most 200 rows aggregated across collections. GET /api/datasets/{id} returns one dataset by numeric id as { links, dataset }, not a collection-scoped detail response. Unknown GET paths under /api respond with 404 and application/problem+json including links to /api, /api/openapi, and /llms.txt."},"components":{"schemas":{"ColumnSchema":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"description":{"type":["string","null"]},"nullable":{"type":"boolean"},"num_null_values":{"type":["number","null"]},"num_unique_values":{"type":["number","null"]},"example_values":{"type":["array","null"],"items":{"type":"string"}},"min":{"type":["number","null"]},"max":{"type":["number","null"]},"length":{"type":["number","null"]},"possible_values":{"type":["array","null"],"items":{"type":"string"}}},"required":["name","type","nullable"],"additionalProperties":{}},"SpatialDatasetFileMetadata":{"type":"object","properties":{"version":{"type":"string"},"description":{"type":["string","null"]},"size_bytes":{"type":["number","null"]},"mime_type":{"type":["string","null"]},"feature_count":{"type":["number","null"]},"bounds":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"},{"type":"number"},{"type":"number"}]},"geometry_type":{"type":["string","null"]},"invalid_geometry_count":{"type":["number","null"]},"quality_check_passed":{"type":["boolean","null"]},"columns_hash":{"type":["string","null"]},"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnSchema"}}},"required":["version"],"additionalProperties":{}},"DatasetSource":{"type":"object","properties":{"id":{"type":"number"},"file_format_id":{"type":"number"},"storage_location_id":{"type":["number","null"]},"version":{"anyOf":[{"type":"string"},{"type":"number"}]},"source_type":{"$ref":"#/components/schemas/SourceType"},"location":{"$ref":"#/components/schemas/SourceLocation"},"source_metadata":{"allOf":[{"$ref":"#/components/schemas/SpatialDatasetFileMetadata"},{"type":["object","null"]}]},"url":{"type":["string","null"]},"storage_uri":{"type":["string","null"]},"glob_pattern":{"type":["string","null"]},"storage_location":{"$ref":"#/components/schemas/StorageLocation"},"links":{"$ref":"#/components/schemas/ApiLinkMap"},"references_source_id":{"type":["number","null"]},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"}},"required":["id","source_type","location"],"additionalProperties":{}},"SourceType":{"type":"string","enum":["file","api"]},"SourceLocation":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["file"]},"version":{"type":"string"},"path":{"type":"string"}},"required":["version","path"],"additionalProperties":{}},{"type":"object","properties":{"type":{"type":"string","enum":["api"]},"version":{"type":"string"},"url":{"type":"string"},"method":{"type":"string"}},"required":["version","url"],"additionalProperties":{}}]},"StorageLocation":{"type":["object","null"],"properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"backend_type":{"type":"string"},"description":{"type":"string"},"config":{"$ref":"#/components/schemas/StorageLocationConfig"},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"}},"required":["id","name","backend_type"],"additionalProperties":{}},"StorageLocationConfig":{"type":["object","null"],"properties":{"type":{"type":"string"},"version":{"type":"string"},"base_url":{"type":"string"},"bucket":{"type":"string"},"endpoint_url":{"type":"string"}},"required":["version","base_url"],"additionalProperties":{}},"ApiLinkMap":{"type":"object","additionalProperties":{"type":"string"}},"DatasetFile":{"type":"object","properties":{"id":{"type":"number"},"dataset_id":{"type":"number"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"layer_name":{"type":["string","null"]},"source_file_path":{"type":["string","null"]},"file_metadata":{"allOf":[{"$ref":"#/components/schemas/SpatialDatasetFileMetadata"},{"type":["object","null"]}]},"formats":{"type":"array","items":{"$ref":"#/components/schemas/DatasetFormat"}},"links":{"$ref":"#/components/schemas/ApiLinkMap"},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"}},"required":["id","dataset_id","name","slug"],"additionalProperties":{}},"DatasetFormat":{"type":"object","properties":{"format":{"$ref":"#/components/schemas/Format"},"file_format":{"$ref":"#/components/schemas/FileFormat"},"dataset_format":{"$ref":"#/components/schemas/FileFormat"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/DatasetSource"}}},"required":["format","sources"],"additionalProperties":{}},"Format":{"type":"object","properties":{"id":{"type":"number"},"format_type":{"$ref":"#/components/schemas/FormatType"},"name":{"type":"string"},"description":{"type":"string"},"mime_type":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"}},"required":["id","format_type","name"],"additionalProperties":{}},"FormatType":{"type":"string","enum":["geoparquet","pmtiles","geopackage","shapefile","geojson","file_geodatabase"]},"FileFormat":{"type":"object","properties":{"id":{"type":"number"},"file_id":{"type":"number"},"dataset_id":{"type":"number"},"format_id":{"type":"number"},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"}},"required":["id","format_id"],"additionalProperties":{}},"DatasetDetailResponse":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/ApiLinkMap"},"collection":{"$ref":"#/components/schemas/Collection"},"dataset":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"collection_id":{"type":"number"},"tags":{"$ref":"#/components/schemas/DatasetTags"},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"links":{"$ref":"#/components/schemas/ApiLinkMap"},"files":{"type":"array","items":{"$ref":"#/components/schemas/DatasetFile"}}},"required":["id","slug","name"],"additionalProperties":{}}},"required":["links","collection","dataset"],"additionalProperties":{}},"Collection":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"}},"required":["id","slug","name"],"additionalProperties":{}},"DatasetTags":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"DatasetByIdLinks":{"type":"object","properties":{"self":{"type":"string"},"collection":{"type":"string"}},"required":["self"]},"DatasetByIdResponse":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/DatasetByIdLinks"},"dataset":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"collection_id":{"type":"number"},"tags":{"$ref":"#/components/schemas/DatasetTags"},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"links":{"$ref":"#/components/schemas/ApiLinkMap"},"files":{"type":"array","items":{"$ref":"#/components/schemas/DatasetFile"}}},"required":["id","slug","name"],"additionalProperties":{}}},"required":["links","dataset"],"additionalProperties":{}},"DatasetFileResponse":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/ApiLinkMap"},"collection":{"$ref":"#/components/schemas/Collection"},"dataset":{"$ref":"#/components/schemas/Dataset"},"file":{"$ref":"#/components/schemas/DatasetFile"}},"required":["links","collection","dataset","file"],"additionalProperties":{}},"Dataset":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"collection_id":{"type":"number"},"tags":{"$ref":"#/components/schemas/DatasetTags"},"created_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"updated_at":{"type":"string","description":"ISO-like timestamp string from the catalog"},"links":{"$ref":"#/components/schemas/ApiLinkMap"}},"required":["id","slug","name"],"additionalProperties":{}},"DatasetFileSchemaResponse":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/ApiLinkMap"},"collection":{"$ref":"#/components/schemas/Collection"},"dataset":{"$ref":"#/components/schemas/Dataset"},"file":{"type":"object","properties":{"id":{"type":"number"},"dataset_id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"layer_name":{"type":["string","null"]}},"required":["id","dataset_id","slug","name"],"additionalProperties":{}},"versions":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"selected_version":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"schema":{"type":["object","null"],"properties":{"version":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"format_type":{"$ref":"#/components/schemas/FormatType"},"format_name":{"type":"string"},"source_id":{"type":"number"},"storage_location":{"$ref":"#/components/schemas/StorageLocation"},"source":{"$ref":"#/components/schemas/DatasetSource"},"source_metadata":{"allOf":[{"$ref":"#/components/schemas/SpatialDatasetFileMetadata"},{"type":["object","null"]}]},"summary":{"type":"object","properties":{"columnCount":{"type":"number"},"featureCount":{"type":["number","null"]},"geometryType":{"type":["string","null"]},"invalidGeometryCount":{"type":["number","null"]},"qualityCheckPassed":{"type":["boolean","null"]},"columnsHash":{"type":["string","null"]}},"required":["columnCount","featureCount","geometryType","invalidGeometryCount","qualityCheckPassed","columnsHash"],"additionalProperties":{}},"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnSchema"}}},"required":["version","format_type","format_name","source_id","source","source_metadata","summary","columns"]}},"required":["links","collection","dataset","file","versions","selected_version","schema"],"additionalProperties":{}},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"instance":{"type":"string"},"links":{"$ref":"#/components/schemas/ApiLinkMap"}},"required":["type","title","status"]}},"parameters":{}},"paths":{"/api":{"get":{"summary":"API bootstrap and discovery","description":"Entry point with links to OpenAPI, /llms.txt, and collections. Call this first; do not assume OGC API-Features or STAC paths (/items, /features, ?q= on random segments).","responses":{"200":{"description":"Bootstrap JSON (title, description, links, hints)","content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"links":{"$ref":"#/components/schemas/ApiLinkMap"},"hints":{"type":"object","additionalProperties":{"type":"string"}}},"required":["title","description","links"],"additionalProperties":{}}}}}}}},"/api/openapi":{"get":{"summary":"OpenAPI 3.1 document for this webapp surface","responses":{"200":{"description":"OpenAPI JSON","content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}}}}},"/api/health":{"get":{"summary":"Liveness / health","description":"Returns JSON suitable for RFC 9727 API catalog status links.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}},"required":["status"]}}}}}}},"/api/collections":{"get":{"summary":"List collections","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"name":{"type":"string"},"links":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]}},"required":["id","slug","name"],"additionalProperties":{}}}}}}}}},"/api/collections/{slug}":{"get":{"summary":"List datasets in a collection (paginated)","description":"This is the only collection-level list route: text search, tag filters, and pagination apply here (search, query, tag_filters, limit, offset, omit, include_urls). There is no /api/collections/{slug}/items, no ?q= shortcut on other paths, and no numeric dataset id in this URL—use dataset slug under .../datasets/{datasetSlug} next.","parameters":[{"schema":{"type":"string","description":"Alias for text filter (same effect as search on this route)"},"required":false,"description":"Alias for text filter (same effect as search on this route)","name":"query","in":"query"},{"schema":{"type":"string","description":"Filter datasets by text; use this or query, not q= on invented paths"},"required":false,"description":"Filter datasets by text; use this or query, not q= on invented paths","name":"search","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"description":"Defaults to 50 when omitted"},"required":false,"description":"Defaults to 50 when omitted","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_urls","in":"query"},{"schema":{"type":"string","description":"Use GET .../datasets/tags to discover allowed values"},"required":false,"description":"Use GET .../datasets/tags to discover allowed values","name":"tag_filters","in":"query"},{"schema":{"type":"string","description":"Comma-separated; use 'description' to omit long descriptions"},"required":false,"description":"Comma-separated; use 'description' to omit long descriptions","name":"omit","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"}},"required":["id","slug"],"additionalProperties":{}},"datasets":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"links":{"$ref":"#/components/schemas/ApiLinkMap"}},"required":["slug"],"additionalProperties":{}}},"total":{"type":"number"},"limit":{"type":["number","null"]},"offset":{"type":"number"},"links":{"$ref":"#/components/schemas/ApiLinkMap"}},"required":["collection","datasets","total","limit","offset"],"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/collections/{collectionSlug}/datasets/tags":{"get":{"summary":"Tag facets for filter discovery","parameters":[{"schema":{"type":"string"},"required":false,"name":"tag_key","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"links":{"$ref":"#/components/schemas/ApiLinkMap"},"tags":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["links","tags"],"additionalProperties":{}}}}}}}},"/api/collections/{collectionSlug}/datasets/{datasetSlug}":{"get":{"summary":"Dataset detail in a collection","description":"Returns one dataset by collection and dataset slug. Use include_urls=true when source URLs are needed on nested file format sources.","parameters":[{"schema":{"type":"string"},"required":true,"name":"collectionSlug","in":"path"},{"schema":{"type":"string"},"required":true,"name":"datasetSlug","in":"path"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"include_urls","in":"query"}],"responses":{"200":{"description":"Dataset detail with file links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetDetailResponse"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/collections/{collectionSlug}/datasets/{datasetSlug}/files/{fileSlug}":{"get":{"summary":"Dataset file metadata and source URLs","description":"Raw file metadata used by the View metadata action. Includes formats, source versions, storage locations, source lifecycle timestamps, source_metadata.description, source_metadata.size_bytes, and download links.","parameters":[{"schema":{"type":"string"},"required":true,"name":"collectionSlug","in":"path"},{"schema":{"type":"string"},"required":true,"name":"datasetSlug","in":"path"},{"schema":{"type":"string"},"required":true,"name":"fileSlug","in":"path"}],"responses":{"200":{"description":"Dataset file metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetFileResponse"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/collections/{collectionSlug}/datasets/{datasetSlug}/files/{fileSlug}/schema":{"get":{"summary":"Dataset file schema and data dictionary","description":"Focused schema metadata for a dataset file. Returns the best schema-capable source for the requested version, including data dictionary columns. Omit version to use the latest schema-capable version.","parameters":[{"schema":{"type":"string"},"required":true,"name":"collectionSlug","in":"path"},{"schema":{"type":"string"},"required":true,"name":"datasetSlug","in":"path"},{"schema":{"type":"string"},"required":true,"name":"fileSlug","in":"path"},{"schema":{"type":"string"},"required":false,"name":"version","in":"query"}],"responses":{"200":{"description":"Dataset file schema metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetFileSchemaResponse"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/datasets":{"get":{"summary":"List datasets (capped aggregate across collections)","responses":{"200":{"description":"JSON array; each row may include links","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"slug":{"type":"string"},"links":{"$ref":"#/components/schemas/ApiLinkMap"}},"required":["id","slug"],"additionalProperties":{}}}}}}}}},"/api/datasets/{id}":{"get":{"summary":"Dataset detail by numeric id","description":"Returns one dataset by numeric id using the global dataset lookup route. The live response is { links, dataset }; it is not collection-scoped and does not include a top-level collection object.","parameters":[{"schema":{"type":"integer"},"required":true,"description":"Numeric dataset id","name":"id","in":"path"}],"responses":{"200":{"description":"Dataset detail with links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetByIdResponse"}}}},"400":{"description":"Invalid ID","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Dataset not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"502":{"description":"Failed to load dataset","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/datasets/stats":{"get":{"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"ready":{"type":"number"},"links":{"$ref":"#/components/schemas/ApiLinkMap"}},"required":["total"],"additionalProperties":{}}}}}}}}},"webhooks":{}}