{"openapi":"3.0.0","info":{"version":"0.1.14 - 0336e74","title":"GIS.PH API","description":"Public OpenAPI document. Tag visibility is controlled in `src/lib/openapi-visible-tags.ts` (comment out tags to hide from /doc and /reference)."},"tags":[{"name":"Index"},{"name":"Regions"},{"name":"Provinces"},{"name":"Municities"},{"name":"Barangays"},{"name":"Datasets"},{"name":"Features"},{"name":"API Keys"},{"name":"Webhooks"},{"name":"Admin"}],"components":{"schemas":{},"parameters":{}},"paths":{"/":{"get":{"tags":["Index"],"summary":"API root","description":"Friendly root response with pointers to public docs and site.","responses":{"200":{"description":"API Metadata Index","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"string"},"hint":{"type":"string"},"what_now":{"type":"string"},"fun_fact":{"type":"string"},"tip":{"type":"string"},"version":{"type":"string"}},"required":["message","status","hint","what_now","fun_fact","tip","version"]}}}}}}},"/version":{"get":{"tags":["Index"],"summary":"API version","description":"Returns package version and runtime environment.","responses":{"200":{"description":"API Version Details (semver + git commit)","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"commit":{"type":"string"},"commitFull":{"type":"string"},"label":{"type":"string"},"name":{"type":"string"},"environment":{"type":"string"},"builtAt":{"type":"string"}},"required":["version","commit","commitFull","label","name","environment"]}}}}}}},"/healthcheck":{"get":{"tags":["Index"],"summary":"Health check","description":"Liveness probe for load balancers and uptime monitors.","responses":{"200":{"description":"API Health Status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"label":{"type":"string"}},"required":["status","version","label"]}}}}}}},"/v1":{"get":{"tags":["Index"],"summary":"API root","description":"Friendly root response with pointers to public docs and site.","responses":{"200":{"description":"API Metadata Index","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"status":{"type":"string"},"hint":{"type":"string"},"what_now":{"type":"string"},"fun_fact":{"type":"string"},"tip":{"type":"string"},"version":{"type":"string"}},"required":["message","status","hint","what_now","fun_fact","tip","version"]}}}}}}},"/v1/version":{"get":{"tags":["Index"],"summary":"API version","description":"Returns package version and runtime environment.","responses":{"200":{"description":"API Version Details (semver + git commit)","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"commit":{"type":"string"},"commitFull":{"type":"string"},"label":{"type":"string"},"name":{"type":"string"},"environment":{"type":"string"},"builtAt":{"type":"string"}},"required":["version","commit","commitFull","label","name","environment"]}}}}}}},"/v1/healthcheck":{"get":{"tags":["Index"],"summary":"Health check","description":"Liveness probe for load balancers and uptime monitors.","responses":{"200":{"description":"API Health Status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"label":{"type":"string"}},"required":["status","version","label"]}}}}}}},"/v1/regions":{"get":{"summary":"List regions","description":"Returns a paginated list of Philippine regions (JSON). When format=geojson, returns an unpaginated FeatureCollection of all matching regions (no parent filter). Geometry level defaults to simple for geojson.","tags":["Regions"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"type":"string","enum":["simple","medium","detailed"],"description":"Boundary resolution: `simple` | `medium` | `detailed`. For `format=json`, omit to exclude geometry. For `format=geojson`, defaults to `simple`.","example":"simple"},"required":false,"name":"geometry","in":"query"},{"schema":{"type":"string","description":"Filter regions by name (case-insensitive partial match)","example":"Luzon"},"required":false,"name":"search","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Filter by one or more region codes (e.g. codes[]=01&codes[]=NCR)"},"required":false,"name":"codes","in":"query"}],"responses":{"200":{"description":"The list of regions, or a GeoJSON FeatureCollection when output=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"code":{"type":"string","maxLength":15},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["id","name","code"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"},"next":{"type":"number","nullable":true},"prev":{"type":"number","nullable":true},"links":{"type":"object","properties":{"self":{"type":"string"},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}},"required":["self","next","prev"]}},"required":["total","page","limit","totalPages","next","prev","links"]},"error":{"nullable":true}},"required":["data","meta","error"]},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/regions/search":{"post":{"summary":"Search regions by IDs","description":"Accepts region IDs and returns either JSON data or a GeoJSON FeatureCollection.","tags":["Regions"],"requestBody":{"description":"Region search payload","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"List of region PSGC codes","example":["0100000000","0200000000"]},"geometry":{"type":"string","enum":["simple","medium","detailed"],"default":"simple","description":"Geometry level to include in response","example":"simple"},"format":{"type":"string","enum":["json","geojson"],"description":"Response format. Use `geojson` for a GeoJSON FeatureCollection.","example":"geojson"},"output":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true}},"required":["ids"]}}}},"responses":{"200":{"description":"Array of regions or GeoJSON FeatureCollection","content":{"application/json":{"schema":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"code":{"type":"string","maxLength":15},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["id","name","code"]}},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/regions/{id}":{"get":{"summary":"Get a region by PSGC code","description":"Returns detailed information about a single region identified by its PSGC code (not the internal serial id). Optional output format as GeoJSON Feature.","tags":["Regions"],"parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^\\d{1,15}$","description":"Philippine Standard Geographic Code (PSGC). Use the 10-digit code when available (e.g. `0730600041`).","example":"0730600041"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"type":"string","enum":["simple","medium","detailed"],"description":"Boundary resolution: `simple` | `medium` | `detailed`. For `format=json`, omit to exclude geometry. For `format=geojson`, defaults to `simple`.","example":"simple"},"required":false,"name":"geometry","in":"query"}],"responses":{"200":{"description":"The requested region, or a GeoJSON Feature when format=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"code":{"type":"string","maxLength":15},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["id","name","code"]},"error":{"nullable":true}},"required":["data","error"]},{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}]}}}},"404":{"description":"Region not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"example":{"message":"Not Found"}}}}},"422":{"description":"Invalid PSGC code","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["id"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/provinces":{"get":{"summary":"List provinces","description":"Returns a paginated list of Philippine provinces (JSON). When format=geojson, returns an unpaginated FeatureCollection; region is optional. Geometry level defaults to simple for geojson.","tags":["Provinces"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"type":"string","enum":["simple","medium","detailed"],"description":"Boundary resolution: `simple` | `medium` | `detailed`. For `format=json`, omit to exclude geometry. For `format=geojson`, defaults to `simple`.","example":"simple"},"required":false,"name":"geometry","in":"query"},{"schema":{"type":"string","description":"Optional parent filter by region code or exact name. Recommended for format=geojson; not required (all provinces may be returned).","example":"07"},"required":false,"name":"region","in":"query"}],"responses":{"200":{"description":"The list of provinces, or a GeoJSON FeatureCollection when format=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"code":{"type":"string","maxLength":15},"r_code":{"type":"string","nullable":true,"maxLength":15}},"required":["id","name","code","r_code"]}},"meta":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"},"next":{"type":"number","nullable":true},"prev":{"type":"number","nullable":true},"links":{"type":"object","properties":{"self":{"type":"string"},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}},"required":["self","next","prev"]}},"required":["total","page","limit","totalPages","next","prev","links"]},"error":{"nullable":true}},"required":["data","meta","error"]},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/provinces/{id}":{"get":{"summary":"Get a province by PSGC code","description":"Returns detailed information about a single province identified by its PSGC code (not the internal serial id). Pass `geometry=true` to include municipality GeoJSON boundaries, or `geometry=simple|medium|detailed` with `format=geojson` to get a bare Feature.","tags":["Provinces"],"parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^\\d{1,15}$","description":"Philippine Standard Geographic Code (PSGC). Use the 10-digit code when available (e.g. `0730600041`).","example":"0730600041"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["simple","medium","detailed"]},{"type":"string","enum":["true"]}],"description":"Include boundary geometry (simple|medium|detailed), or set to 'true' to include nested municipality GeoJSON boundaries.","example":"simple"},"required":false,"name":"geometry","in":"query"}],"responses":{"200":{"description":"The requested province, or a GeoJSON Feature when format=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"code":{"type":"string","maxLength":15},"r_code":{"type":"string","nullable":true,"maxLength":15}},"required":["id","name","code","r_code"]},"geojson":{"nullable":true},"error":{"nullable":true}},"required":["data","error"]},{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}]}}}},"404":{"description":"Province not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"example":{"message":"Not Found"}}}}},"422":{"description":"Invalid PSGC code","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["id"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/provinces/search":{"post":{"summary":"Search provinces by PSGC codes","description":"Returns provinces matching the given PSGC codes. Optionally includes geometry from R2.","tags":["Provinces"],"requestBody":{"description":"Province search payload","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codes":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"Array of province PSGC codes to search for","example":["1206500000","1204700000","0701200000"]},"geometry":{"type":"string","enum":["simple","medium","detailed"],"default":"simple","description":"Geometry level to include in response"},"format":{"type":"string","enum":["json","geojson"],"description":"Response format. Use `geojson` for a GeoJSON FeatureCollection.","example":"geojson"},"output":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true}},"required":["codes"]}}}},"responses":{"200":{"description":"Matching provinces","content":{"application/json":{"schema":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"code":{"type":"string","maxLength":15},"r_code":{"type":"string","nullable":true,"maxLength":15}},"required":["id","name","code","r_code"]}},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/datasets":{"get":{"summary":"List datasets","description":"Returns datasets for the caller as `{ data, meta, error }`. Supports page/limit, includeFeatures, visibility, and admin user_email filters.","tags":["Datasets"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"When true, include related features in each dataset.","example":"true"},"required":false,"name":"includeFeatures","in":"query"},{"schema":{"type":"string","description":"Filter datasets by owner email (admin only)."},"required":false,"name":"user_email","in":"query"},{"schema":{"type":"string","enum":["public","private","all","mine"],"description":"Filter datasets by visibility. Ownership is datasets.user_id (= profile.uid). For authenticated users (API key / JWT / master+Clerk): default and 'mine' = user_id = you OR user_email matches your auth email; 'private' = your non-public owned datasets; 'all' = yours + every public dataset; 'public' = public catalog only. Admins (master token without resolved user) see all unless user_email is set."},"required":false,"name":"visibility","in":"query"},{"schema":{"type":"string","description":"When true, include scope debug fields on meta."},"required":false,"name":"debug","in":"query"}],"responses":{"200":{"description":"Paginated list of datasets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"features":{"type":"array","items":{"type":"object","properties":{}}}}}},"meta":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"},"next":{"type":"number","nullable":true},"prev":{"type":"number","nullable":true},"links":{"type":"object","properties":{"self":{"type":"string"},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}},"required":["self","next","prev"]}},"required":["total","page","limit","totalPages","next","prev","links"]},"error":{"nullable":true}},"required":["data","meta","error"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"post":{"summary":"Create a dataset","description":"Creates a dataset, optionally with inline features (geom or geometry required per feature).","tags":["Datasets"],"requestBody":{"description":"The dataset to create","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"user_id":{"type":"string","format":"uuid"},"user_email":{"type":"string","nullable":true,"format":"email"},"description":{"type":"string","nullable":true},"is_public":{"type":"boolean"},"data_type":{"type":"string","enum":["vector","raster","data"]},"srid":{"type":"integer"},"geometry_type":{"type":"string","nullable":true},"status":{"type":"string"},"metadata":{"nullable":true},"storage_ref":{"type":"string","nullable":true},"features":{"type":"array","items":{"type":"object","properties":{"geom":{"nullable":true},"geometry":{"nullable":true},"properties":{"nullable":true}}}}},"required":["name"]}}}},"responses":{"200":{"description":"The created dataset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"features":{"type":"array","items":{"type":"object","properties":{}}}}},"error":{"nullable":true}},"required":["data","error"]}}}},"422":{"description":"Validation / Upstream error","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["name"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/datasets/upload":{"post":{"summary":"Upload a dataset file","description":"Uploads a GeoJSON or other supported file as a new dataset (multipart form-data).","tags":["Datasets"],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"GeoJSON or other supported dataset file","format":"binary"},"name":{"type":"string","description":"Dataset name (defaults to filename)"},"description":{"type":"string","description":"Dataset description"},"data_type":{"type":"string","enum":["vector","raster","data"],"description":"Type of data"},"srid":{"type":"integer","nullable":true,"description":"Spatial Reference System Identifier (default: 4326)"},"geometry_type":{"type":"string","description":"Geometry type (e.g., POINT, POLYGON)"},"status":{"type":"string","description":"Dataset status"},"user_email":{"type":"string","format":"email","description":"Owner email address"},"dataset_id":{"type":"string","format":"uuid","description":"When set, replace this existing dataset (same id) — re-upload. Requires feature_storage (or materialize_features) to choose features+R2 vs R2-only."},"feature_storage":{"type":"string","enum":["features_and_r2","r2_only"],"description":"Required when dataset_id is set (re-upload). `features_and_r2` = R2 snapshot + insert rows into features table (webmaps/dashboard). `r2_only` = R2 file only; features table cleared; file is source of truth. For new uploads (no dataset_id), optional; defaults: GeoJSON→features_and_r2, shapefile→r2_only."},"materialize_features":{"type":"string","description":"Legacy alias of feature_storage. `true`/`1`/`yes` → features_and_r2; `false`/`0`/`no` → r2_only. When dataset_id is set, either feature_storage or materialize_features is required."}},"required":["file"]}}}},"responses":{"200":{"description":"The uploaded dataset with storage reference","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"features":{"type":"array","items":{"type":"object","properties":{}}}}},"error":{"nullable":true}},"required":["data","error"]}}}},"400":{"description":"No file provided","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Upload / Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/datasets/:id":{"get":{"summary":"Get a dataset by ID","description":"Returns a single dataset by UUID. Optionally include related features.","tags":["Datasets"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"When true, include related features in the dataset.","example":"true"},"required":false,"name":"includeFeatures","in":"query"}],"responses":{"200":{"description":"The dataset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"features":{"type":"array","items":{"type":"object","properties":{}}}}},"error":{"nullable":true}},"required":["data","error"]}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/datasets/{id}":{"patch":{"summary":"Update a dataset","description":"Partially updates dataset metadata and optional feature payload.","tags":["Datasets"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The dataset fields to update","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"user_id":{"type":"string","format":"uuid"},"user_email":{"type":"string","nullable":true,"format":"email"},"description":{"type":"string","nullable":true},"is_public":{"type":"boolean"},"data_type":{"type":"string","enum":["vector","raster","data"]},"srid":{"type":"integer"},"geometry_type":{"type":"string","nullable":true},"status":{"type":"string"},"metadata":{"nullable":true},"storage_ref":{"type":"string","nullable":true},"features":{"type":"array","items":{"type":"object","properties":{"geom":{"nullable":true},"geometry":{"nullable":true},"properties":{"nullable":true}}}}}}}}},"responses":{"200":{"description":"The updated dataset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"features":{"type":"array","items":{"type":"object","properties":{}}}}},"error":{"nullable":true}},"required":["data","error"]}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Validation / Upstream error","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"]}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"delete":{"summary":"Delete a dataset","description":"Deletes a dataset by UUID.","tags":["Datasets"],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Dataset deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/features":{"get":{"summary":"List features","description":"Returns geographic features.","tags":["Features"],"responses":{"200":{"description":"The list of features","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{}}},"error":{"nullable":true}},"required":["data","error"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"post":{"summary":"Create a feature","description":"Creates a feature on a dataset. Provide geom or geometry.","tags":["Features"],"requestBody":{"description":"The feature to create","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid"},"geom":{"nullable":true},"geometry":{"nullable":true},"properties":{"nullable":true}},"required":["dataset_id"]}}}},"responses":{"200":{"description":"The created feature","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}},"error":{"nullable":true}},"required":["data","error"]}}}},"404":{"description":"Dataset not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Validation / Upstream error","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["dataset_id"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/features/{id}":{"get":{"summary":"Get a feature by ID","description":"Returns a single feature by id.","tags":["Features"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Feature id","example":"1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The requested feature","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}},"error":{"nullable":true}},"required":["data","error"]}}}},"404":{"description":"Feature not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"example":{"message":"Not Found"}}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"patch":{"summary":"Update a feature","description":"Partially updates a feature's geometry and properties.","tags":["Features"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Feature id","example":"1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The feature fields to update","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataset_id":{"type":"string","format":"uuid"},"geom":{"nullable":true},"geometry":{"nullable":true},"properties":{"nullable":true}}}}}},"responses":{"200":{"description":"The updated feature","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}},"error":{"nullable":true}},"required":["data","error"]}}}},"404":{"description":"Feature not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"example":{"message":"Not Found"}}}}},"422":{"description":"Validation / Upstream error","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"]}},"required":["success","error"]},{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/features/dataset/{datasetId}":{"get":{"summary":"List features for a dataset","description":"Returns all features belonging to the given dataset UUID.","tags":["Features"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Dataset id","example":"b2c3d4e5-f6g7-8901-bcde-fg2345678901"},"required":true,"name":"datasetId","in":"path"}],"responses":{"200":{"description":"The list of features for a dataset","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{}}},"error":{"nullable":true}},"required":["data","error"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/api-keys":{"get":{"summary":"List API keys","description":"Returns API keys for the authenticated user or org. Plaintext secrets are never returned on list.","tags":["API Keys"],"responses":{"200":{"description":"The list of API keys (no plaintext keys)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true}},"error":{"nullable":true}},"required":["data","error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"post":{"summary":"Create an API key","description":"Creates an API key. The plaintext key is returned only once in this response; store it immediately.","tags":["API Keys"],"requestBody":{"description":"API key creation request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"scopes":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Optional scopes (e.g. read:boundaries, write:datasets). Null/empty = full access for the key. Enforced at request time.","example":["read:boundaries","read:datasets"]},"rate_limit_rpm":{"type":"integer","nullable":true,"description":"Requests per minute for this key. Null uses platform default (60). Enforced at request time via Upstash when configured.","example":60},"rate_limit_burst":{"type":"integer","nullable":true,"description":"Reserved for future burst/token-bucket; currently unused (window cap is rpm).","example":100},"environment":{"type":"string","enum":["live","test"]},"user_id":{"type":"string","nullable":true,"format":"uuid"},"user_email":{"type":"string","nullable":true,"format":"email"}},"required":["name"]}}}},"responses":{"200":{"description":"The created API key (plaintext returned once)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true},"error":{"nullable":true}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Validation / Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["name"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/api-keys/{id}/revoke":{"post":{"summary":"Revoke an API key","description":"Revokes an API key by UUID so it can no longer authenticate requests.","tags":["API Keys"],"parameters":[{"schema":{"type":"string","format":"uuid","required":["id"],"example":"4651e634-a530-4484-9b09-9616a28f35e3"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"nullable":true},"error":{"nullable":true}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"API key not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/api-keys/stats":{"get":{"summary":"API key usage statistics","description":"Returns aggregate usage stats for the caller's keys (request counts, rates, optional daily breakdown).","tags":["API Keys"],"responses":{"200":{"description":"API key statistics","content":{"application/json":{"schema":{"type":"object","properties":{"total_keys":{"type":"number"},"total_requests":{"type":"number"},"avg_response_time":{"type":"number"},"success_rate":{"type":"number"},"error_rate":{"type":"number"},"requests_by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"count":{"type":"number"}},"required":["date","count"]}},"top_endpoints":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","nullable":true},"count":{"type":"number"}},"required":["path","count"]}}},"required":["total_keys","total_requests","avg_response_time","success_rate","error_rate"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/webhooks/clerk":{"post":{"summary":"Clerk webhook receiver","description":"Accepts signed Clerk webhook events (user/org lifecycle). Validates signature before processing.","tags":["Webhooks"],"requestBody":{"description":"Clerk webhook payload","required":true,"content":{"application/json":{"schema":{"nullable":true}}}},"responses":{"200":{"description":"Webhook accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"received":{"type":"boolean"}},"required":["received"]},"error":{"nullable":true}},"required":["data","error"]}}}},"401":{"description":"Invalid signature","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Webhook secret missing or server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/webhooks/resend":{"post":{"summary":"Resend webhook receiver","description":"Accepts signed Resend (email) webhook events. Validates signature before processing.","tags":["Webhooks"],"requestBody":{"description":"Resend webhook payload","required":true,"content":{"application/json":{"schema":{"nullable":true}}}},"responses":{"200":{"description":"Webhook accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"received":{"type":"boolean"}},"required":["received"]},"error":{"nullable":true}},"required":["data","error"]}}}},"401":{"description":"Invalid signature","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Webhook secret missing or server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/webhooks/ping":{"get":{"summary":"Webhook health check","description":"Simple health/ping endpoint for webhook routing checks.","tags":["Webhooks"],"responses":{"200":{"description":"Webhook health check","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"ok":{"type":"boolean"},"message":{"type":"string"}},"required":["ok","message"]},"error":{"nullable":true}},"required":["data","error"]}}}}}}},"/v1/municities/search":{"get":{"summary":"Search cities and municipalities globally","description":"Search for cities and municipalities across all provinces using a text query. Returns enriched data with province names.","tags":["Municities"],"parameters":[{"schema":{"type":"string","minLength":2,"description":"Search query (min 2 chars)","example":"Tagbilaran"},"required":true,"name":"q","in":"query"},{"schema":{"type":"number","nullable":true,"default":20,"description":"Max results to return","example":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true}},"error":{"nullable":true}},"required":["data","error"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}},"post":{"summary":"Search municipalities/cities by PSGC codes","description":"Returns municipalities/cities matching the given PSGC codes. Optionally includes geometry from R2.","tags":["Municities"],"requestBody":{"description":"Municipality search payload","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codes":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":1000,"description":"Array of municipality/city PSGC codes to search for","example":["0701244000","0304905000","0300812000"]},"geometry":{"type":"string","enum":["simple","medium","detailed"],"default":"simple","description":"Geometry level to include in response"},"format":{"type":"string","enum":["json","geojson"],"description":"Response format. Use `geojson` for a GeoJSON FeatureCollection.","example":"geojson"},"output":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true}},"required":["codes"]}}}},"responses":{"200":{"description":"Matching municipalities","content":{"application/json":{"schema":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"type":{"type":"string","maxLength":20},"code":{"type":"string","maxLength":15},"p_code":{"type":"string","nullable":true,"maxLength":15},"host_province_code":{"type":"string","nullable":true,"maxLength":15},"city_class":{"type":"string","nullable":true,"maxLength":10}},"required":["id","name","type","code","p_code","host_province_code","city_class"]}},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/municities":{"get":{"summary":"List cities and municipalities","description":"Returns a paginated list of Philippine cities and municipalities. Filtering by province is required (exact name match). By default `scope=geographic` includes component LGUs and HUC/ICC cities hosted in that province (e.g. Cebu City under Cebu). Pass `scope=admin` to return only LGUs whose admin PSGC parent is the province (excludes HUCs). When format=geojson, returns an unpaginated FeatureCollection (geometry defaults to simple).","tags":["Municities"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"type":"string","enum":["simple","medium","detailed"],"description":"Boundary resolution: `simple` | `medium` | `detailed`. For `format=json`, omit to exclude geometry. For `format=geojson`, defaults to `simple`.","example":"simple"},"required":false,"name":"geometry","in":"query"},{"schema":{"type":"string","minLength":1,"example":"Bohol"},"required":true,"name":"province","in":"query"},{"schema":{"type":"string","enum":["geographic","admin"],"default":"geographic","description":"Province membership model. `geographic` (default) includes HUC/ICC hosted in the province for UX lists. `admin` returns only LGUs whose admin parent is the province (excludes HUCs).","example":"geographic"},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","description":"Starts with search for city or municipality name","example":"Tagbilaran"},"required":false,"name":"name","in":"query"}],"responses":{"200":{"description":"The list of cities and municipalities, or a GeoJSON FeatureCollection when format=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true}},"meta":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"},"next":{"type":"number","nullable":true},"prev":{"type":"number","nullable":true},"links":{"type":"object","properties":{"self":{"type":"string"},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}},"required":["self","next","prev"]}},"required":["total","page","limit","totalPages","next","prev","links"]},"error":{"nullable":true}},"required":["data","meta","error"]},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"400":{"description":"Validation error (e.g., missing province)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/municities/{id}":{"get":{"summary":"Get a municipality by PSGC code","description":"Returns detailed information about a single city or municipality identified by its PSGC code (not the internal serial id). Pass `geometry=true` to include nested barangay GeoJSON boundaries, or `geometry=simple|medium|detailed` with `format=geojson` to get a bare Feature.","tags":["Municities"],"parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^\\d{1,15}$","description":"Philippine Standard Geographic Code (PSGC). Use the 10-digit code when available (e.g. `0730600041`).","example":"0730600041"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["simple","medium","detailed"]},{"type":"string","enum":["true"]}],"description":"Include boundary geometry (simple|medium|detailed), or set to 'true' to include nested barangay GeoJSON boundaries.","example":"simple"},"required":false,"name":"geometry","in":"query"}],"responses":{"200":{"description":"The requested city/municipality, or a GeoJSON Feature when format=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"name":{"type":"string","maxLength":256},"type":{"type":"string","maxLength":20},"code":{"type":"string","maxLength":15},"p_code":{"type":"string","nullable":true,"maxLength":15},"host_province_code":{"type":"string","nullable":true,"maxLength":15},"city_class":{"type":"string","nullable":true,"maxLength":10}},"required":["id","name","type","code","p_code","host_province_code","city_class"]},"geojson":{"nullable":true},"error":{"nullable":true}},"required":["data","error"]},{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}]}}}},"404":{"description":"City/municipality not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Invalid PSGC code","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["id"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/barangays":{"get":{"summary":"List barangays","description":"Returns a paginated list of Philippine barangays. Province is always required. When format=geojson, municipality is also required and the response is an unpaginated FeatureCollection (geometry defaults to simple).","tags":["Barangays"],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"type":"string","enum":["simple","medium","detailed"],"description":"Boundary resolution: `simple` | `medium` | `detailed`. For `format=json`, omit to exclude geometry. For `format=geojson`, defaults to `simple`.","example":"simple"},"required":false,"name":"geometry","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Exact (case-insensitive) name of the province","example":"Bohol"},"required":true,"name":"province","in":"query"},{"schema":{"type":"string","description":"Starts-with search for municipality or city name. Required when format=geojson (prevents province-wide dumps).","example":"Tagbilaran"},"required":false,"name":"municipality","in":"query"},{"schema":{"type":"string","description":"Starts with search for barangay name","example":"Poblacion"},"required":false,"name":"name","in":"query"}],"responses":{"200":{"description":"The list of barangays, or a GeoJSON FeatureCollection when format=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true}},"meta":{"type":"object","properties":{"total":{"type":"number"},"page":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"},"next":{"type":"number","nullable":true},"prev":{"type":"number","nullable":true},"links":{"type":"object","properties":{"self":{"type":"string"},"next":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true}},"required":["self","next","prev"]}},"required":["total","page","limit","totalPages","next","prev","links"]},"error":{"nullable":true}},"required":["data","meta","error"]},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"400":{"description":"Validation error (e.g., missing province)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Upstream/Supabase error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/barangays/search":{"get":{"summary":"Search barangays globally","description":"Search for barangays across all provinces. Multi-word queries are tokenized on spaces/commas and all tokens must match (name, municipality, province, region, or full address). Examples: `poblacion bat`, `san jose laguna`, `Poblacion, Cebu`, `Lahug NIR`.","tags":["Barangays"],"parameters":[{"schema":{"type":"string","minLength":2,"description":"Free-text search (min 2 chars). Spaces and commas split tokens; every token must match.","example":"poblacion bat"},"required":true,"name":"q","in":"query"},{"schema":{"type":"number","nullable":true,"default":20,"description":"Max results to return","example":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"nullable":true}},"error":{"nullable":true}},"required":["data","error"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}},"post":{"summary":"Search barangays by PSGC codes","description":"Returns barangays matching the given PSGC codes. Optionally includes geometry from R2.","tags":["Barangays"],"requestBody":{"description":"Barangay search payload","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"codes":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":500,"description":"Array of barangay PSGC codes to search for","example":["0701201001","0701201006"]},"geometry":{"type":"string","enum":["simple","medium","detailed"],"default":"simple","description":"Geometry level to include in response"},"format":{"type":"string","enum":["json","geojson"],"description":"Response format. Use `geojson` for a GeoJSON FeatureCollection.","example":"geojson"},"output":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true}},"required":["codes"]}}}},"responses":{"200":{"description":"Matching barangays","content":{"application/json":{"schema":{"anyOf":[{"type":"array","items":{"nullable":true}},{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}}},"required":["type","features"]}]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/barangays/{id}":{"get":{"summary":"Get a barangay by PSGC code","description":"Returns detailed information about a single barangay identified by its PSGC code (not the internal serial id). Optional output format as GeoJSON Feature.","tags":["Barangays"],"parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^\\d{1,15}$","description":"Philippine Standard Geographic Code (PSGC). Use the 10-digit code when available (e.g. `0730600041`).","example":"0730600041"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Response representation. `json` (default) returns the standard `{ data, meta?, error }` envelope. `geojson` returns a bare GeoJSON FeatureCollection (collections) or Feature (get-one). Geometry level defaults to `simple` when omitted.","example":"geojson"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["json","geojson"],"description":"Deprecated alias of `format`. Prefer `format`.","example":"geojson","deprecated":true},"required":false,"name":"output","in":"query"},{"schema":{"type":"string","enum":["simple","medium","detailed"],"description":"Boundary resolution: `simple` | `medium` | `detailed`. For `format=json`, omit to exclude geometry. For `format=geojson`, defaults to `simple`.","example":"simple"},"required":false,"name":"geometry","in":"query"}],"responses":{"200":{"description":"The requested barangay, or a GeoJSON Feature when format=geojson","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"nullable":true},"error":{"nullable":true}},"required":["error"]},{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"geometry":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"properties":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}}},"required":["type","geometry","properties"]}]}}}},"404":{"description":"Barangay not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"422":{"description":"Invalid PSGC code","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"message":{"type":"string"}},"required":["code","path"]}},"name":{"type":"string"}},"required":["issues","name"],"example":{"issues":[{"code":"invalid_type","expected":"string","received":"undefined","path":["id"],"message":"Required"}],"name":"ZodError"}}},"required":["success","error"]}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Upstream service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}},"required":["message"]}}}}}}},"/v1/admin/fill-places-admin-codes/{placeId}":{"post":{"summary":"Fill admin codes for one place (PIP reverse geocode)","description":"Resolves region/province/municity/barangay codes from place lat/lng using R2 boundary GeoJSON. Admin or master token required. One place at a time.","tags":["Admin"],"parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"example":205},"required":true,"name":"placeId","in":"path"}],"requestBody":{"description":"Optional dry_run / force / levels","content":{"application/json":{"schema":{"type":"object","properties":{"levels":{"type":"array","items":{"type":"string","enum":["region","province","municity","barangay"]},"description":"Which codes to resolve (default: all four)"},"dry_run":{"type":"boolean","default":false,"description":"If true, compute codes but do not UPDATE the place row"},"force":{"type":"boolean","default":false,"description":"If true, overwrite existing non-null admin codes"},"geometry":{"type":"string","enum":["simple","medium","detailed"],"default":"simple"}}}}}},"responses":{"200":{"description":"Resolved codes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"place_id":{"type":"number"},"dry_run":{"type":"boolean"},"force":{"type":"boolean"},"coords":{"type":"object","nullable":true,"properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"]},"before":{"type":"object","properties":{"region_code":{"type":"string","nullable":true},"province_code":{"type":"string","nullable":true},"municity_code":{"type":"string","nullable":true},"barangay_code":{"type":"string","nullable":true}},"required":["region_code","province_code","municity_code","barangay_code"]},"after":{"type":"object","properties":{"region_code":{"type":"string","nullable":true},"province_code":{"type":"string","nullable":true},"municity_code":{"type":"string","nullable":true},"barangay_code":{"type":"string","nullable":true}},"required":["region_code","province_code","municity_code","barangay_code"]},"resolved":{"type":"object","properties":{"region_code":{"type":"string","nullable":true},"province_code":{"type":"string","nullable":true},"municity_code":{"type":"string","nullable":true},"barangay_code":{"type":"string","nullable":true},"method":{"type":"string"},"unmatched_reason":{"type":"string"}},"required":["region_code","province_code","municity_code","barangay_code","method"]},"changed":{"type":"boolean"},"updated":{"type":"boolean"}},"required":["place_id","dry_run","force","coords","before","after","resolved","changed","updated"]},"error":{"nullable":true}},"required":["data","error"]}}}},"403":{"description":"Admin required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Place not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"example":{"message":"Not Found"}}}}},"422":{"description":"No coordinates or validation error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/admin/job/fill-places-admin-codes":{"post":{"summary":"Enqueue place admin-code fill jobs","description":"Selects places and enqueues one message per place to Supabase queue `fix-places-admin-code-queue`. Does not resolve geometry in this request. Process with POST /v1/admin/job/fill-places-admin-codes/process.","tags":["Admin"],"requestBody":{"description":"Enqueue options","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["missing_only","all"],"default":"missing_only","description":"missing_only = places with coords and at least one null admin code"},"levels":{"type":"array","items":{"type":"string","enum":["region","province","municity","barangay"]}},"force":{"type":"boolean","default":false},"dry_run":{"type":"boolean","default":false,"description":"Passed through to each queue message for the consumer"},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":5000,"description":"Max places to enqueue in this call (default: no limit beyond safety cap)"}}}}}},"responses":{"200":{"description":"Enqueue result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"enqueued":{"type":"integer"},"queue":{"type":"string"},"mode":{"type":"string"},"place_ids":{"type":"array","items":{"type":"number"}}},"required":["job_id","enqueued","queue","mode"]},"error":{"nullable":true}},"required":["data","error"]}}}},"400":{"description":"Bad request / queue error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Admin required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/v1/admin/job/fill-places-admin-codes/process":{"post":{"summary":"Queue process status (Cloudflare push consumer)","description":"Cloudflare Queues delivers messages to the Worker queue() handler automatically. This endpoint is retained for ops docs only and does not drain the queue.","tags":["Admin"],"requestBody":{"description":"Ignored (consumer is push-based)","content":{"application/json":{"schema":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"Max messages to read from the queue this call"},"vt_seconds":{"type":"integer","minimum":10,"maximum":600,"default":90}}}}}},"responses":{"200":{"description":"Guidance only","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"processed":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","items":{"nullable":true}},"note":{"type":"string"}},"required":["processed","succeeded","failed","results"]},"error":{"nullable":true}},"required":["data","error"]}}}},"403":{"description":"Admin required","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}}}}