{
    "openapi": "3.1.0",
    "info": {
        "title": "San Antonio Building Permits API",
        "version": "1.0.0",
        "summary": "Building permit activity for San Antonio, Texas, published with the coverage rate of every field it is computed from.",
        "description": "Read-only, CORS-enabled, cached JSON over the City of San Antonio's own open building-permit record.\n\nThe declared-valuation field is populated on a small minority of permits. Every dollar figure in this API is computed from that minority and is returned beside its coverage rate. A district with more recorded valuation is not necessarily building more; it may simply have had the field filled in more often, and this record cannot tell the two apart.\n\nThe published coordinate columns mix two coordinate systems and contain sign and axis errors, so no point geometry is served. This API aggregates only: it publishes no per-applicant figures, because the permit record names private individuals.\n\nEvery response carries a `caveats` object stating these conditions.",
        "contact": {
            "name": "BrandShyp",
            "url": "https:\/\/brandshyp.org\/contact-us\/"
        },
        "license": {
            "name": "City of San Antonio open data",
            "url": "https:\/\/data.sanantonio.gov\/"
        }
    },
    "externalDocs": {
        "description": "Human documentation, with the tables and the caveats in context",
        "url": "https:\/\/brandshyp.org\/san-antonio-building-permits\/"
    },
    "servers": [
        {
            "url": "https:\/\/brandshyp.org\/api\/v1\/permits"
        }
    ],
    "security": [],
    "tags": [
        {
            "name": "permits",
            "description": "Permit volume and declared valuation"
        },
        {
            "name": "meta",
            "description": "Discovery and data quality"
        }
    ],
    "paths": {
        "\/": {
            "get": {
                "summary": "Discovery document",
                "operationId": "getRoot",
                "tags": [
                    "meta"
                ],
                "responses": {
                    "200": {
                        "description": "Service description and headline coverage, derived live from the dataset.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/summary": {
            "get": {
                "summary": "Citywide totals",
                "operationId": "getSummary",
                "tags": [
                    "permits"
                ],
                "responses": {
                    "200": {
                        "description": "Permit count, valuation coverage, declared valuation and the valuation bands.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/types": {
            "get": {
                "summary": "By permit type",
                "operationId": "getTypes",
                "tags": [
                    "permits"
                ],
                "responses": {
                    "200": {
                        "description": "Each permit type with its permit count, its valuation coverage, and the declared valuation computed from the covered permits only.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/districts": {
            "get": {
                "summary": "By council district",
                "operationId": "getDistricts",
                "tags": [
                    "permits"
                ],
                "responses": {
                    "200": {
                        "description": "Per-district counts and coverage, plus the permits that span several districts or carry none. District 0 is flagged: it is not a council district.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/months": {
            "get": {
                "summary": "Monthly issued volume",
                "operationId": "getMonths",
                "tags": [
                    "permits"
                ],
                "responses": {
                    "200": {
                        "description": "Permits issued per month with that month's valuation coverage. The most recent month is usually partial.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/quality": {
            "get": {
                "summary": "What the record does not contain",
                "operationId": "getQuality",
                "tags": [
                    "meta"
                ],
                "responses": {
                    "200": {
                        "description": "Field coverage, the multi-value district field, the coordinate audit, and what this API deliberately does not publish.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/summary.csv": {
            "get": {
                "summary": "The whole cube as CSV",
                "operationId": "getSummaryCsv",
                "tags": [
                    "permits"
                ],
                "responses": {
                    "200": {
                        "description": "Tidy CSV. Every row carries its own coverage rate.",
                        "content": {
                            "text\/csv": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/openapi.json": {
            "get": {
                "summary": "This document",
                "operationId": "getOpenapi",
                "tags": [
                    "meta"
                ],
                "responses": {
                    "200": {
                        "description": "OpenAPI 3.1 description.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable. It is rebuilt monthly.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "error",
                    "status"
                ],
                "properties": {
                    "error": {
                        "type": "string",
                        "description": "Human-readable explanation."
                    },
                    "status": {
                        "type": "integer",
                        "description": "HTTP status code, repeated in the body."
                    }
                }
            },
            "Caveats": {
                "type": "object",
                "description": "The conditions under which these numbers mean anything. Present on every successful JSON response.",
                "properties": {
                    "valuation_coverage": {
                        "type": "string"
                    },
                    "district_comparison": {
                        "type": "string"
                    },
                    "declared_not_actual": {
                        "type": "string"
                    },
                    "multi_value_district": {
                        "type": "string"
                    },
                    "district_zero": {
                        "type": "string"
                    },
                    "coordinates_unusable": {
                        "type": "string"
                    },
                    "aggregate_only": {
                        "type": "string"
                    },
                    "permit_is_intent": {
                        "type": "string"
                    }
                }
            }
        }
    }
}