{
  "openapi": "3.1.0",
  "info": {
    "title": "CCSTRA Permit Verification Demonstration",
    "version": "1.0.0",
    "description": "Independent, read-only demonstration using the historical City permit snapshot already on CCSTRA. Every response is non-authoritative; current_validity is always unknown. passes_snapshot_check never authorizes a booking. Receipts are unsigned, unretained demo correlation IDs. No API key required. Up to 100 items and 64 KiB per batch."
  },
  "servers": [
    {
      "url": "https://ccstra.org/api/permits/v1"
    }
  ],
  "security": [],
  "paths": {
    "/": {
      "get": {
        "operationId": "getSnapshotMetadata",
        "summary": "Read historical source metadata, counts, examples and limits",
        "responses": {
          "200": {
            "description": "Metadata does not verify any current permit",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "required": [
                        "source",
                        "record_count",
                        "active_in_snapshot",
                        "max_batch_size",
                        "examples"
                      ],
                      "properties": {
                        "source": {
                          "$ref": "#/components/schemas/Source"
                        },
                        "record_count": {
                          "type": "integer"
                        },
                        "unique_permit_numbers": {
                          "type": "integer"
                        },
                        "active_in_snapshot": {
                          "type": "integer"
                        },
                        "max_batch_size": {
                          "const": 100
                        },
                        "examples": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "proposed_recheck_interval_days": {
                          "const": 7
                        },
                        "recheck_note": {
                          "type": "string"
                        },
                        "receipts": {
                          "type": "string"
                        },
                        "documentation": {
                          "type": "string",
                          "format": "uri"
                        },
                        "openapi": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Source unavailable; no decision made",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/verify.php": {
      "post": {
        "operationId": "verifyPermitSnapshot",
        "summary": "Check one permit/address against the historical snapshot",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckRequest"
              },
              "example": {
                "permit_number": "27200",
                "address": "505 Scotland Drive"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completed check, including mismatch or missing permit; never current authorization",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "$ref": "#/components/schemas/CheckResult"
                    },
                    {
                      "type": "object",
                      "required": [
                        "source"
                      ],
                      "properties": {
                        "source": {
                          "$ref": "#/components/schemas/Source"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported method",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "POST requires application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid fields or outer request envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source unavailable; no decision made",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "verifyPermitSnapshotByQuery",
        "summary": "Same check using URL parameters; POST is preferable for address privacy",
        "parameters": [
          {
            "name": "permit_number",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          },
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 256
            }
          },
          {
            "name": "unit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          },
          {
            "name": "reference",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Completed historical check",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "$ref": "#/components/schemas/CheckResult"
                    },
                    {
                      "type": "object",
                      "required": [
                        "source"
                      ],
                      "properties": {
                        "source": {
                          "$ref": "#/components/schemas/Source"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Invalid fields or outer request envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source unavailable; no decision made",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/batch.php": {
      "post": {
        "operationId": "verifyPermitBatch",
        "summary": "Recheck 1\u2013100 properties; does not schedule checks or refresh source data",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "requests"
                ],
                "properties": {
                  "requests": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "$ref": "#/components/schemas/CheckRequest"
                    }
                  }
                }
              },
              "example": {
                "requests": [
                  {
                    "reference": "property-1",
                    "permit_number": "27200",
                    "address": "505 Scotland Drive"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ordered results; invalid entries have http_status 422 while other checks continue",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    {
                      "type": "object",
                      "required": [
                        "source",
                        "count",
                        "summary",
                        "results"
                      ],
                      "properties": {
                        "source": {
                          "$ref": "#/components/schemas/Source"
                        },
                        "count": {
                          "type": "integer"
                        },
                        "summary": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "integer"
                          }
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "allOf": [
                                  {
                                    "$ref": "#/components/schemas/CheckResult"
                                  },
                                  {
                                    "type": "object",
                                    "required": [
                                      "index",
                                      "http_status"
                                    ],
                                    "properties": {
                                      "index": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "http_status": {
                                        "const": 200
                                      }
                                    }
                                  }
                                ]
                              },
                              {
                                "type": "object",
                                "required": [
                                  "index",
                                  "http_status",
                                  "result",
                                  "error",
                                  "current_validity",
                                  "passes_snapshot_check"
                                ],
                                "properties": {
                                  "index": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "http_status": {
                                    "const": 422
                                  },
                                  "result": {
                                    "const": "invalid_input"
                                  },
                                  "current_validity": {
                                    "const": "unknown"
                                  },
                                  "passes_snapshot_check": {
                                    "type": "null"
                                  },
                                  "error": {
                                    "type": "object"
                                  }
                                }
                              }
                            ]
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported method",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request body exceeds 64 KiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "POST requires application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid fields or outer request envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source unavailable; no decision made",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Envelope": {
        "type": "object",
        "required": [
          "api_version",
          "mode",
          "authoritative",
          "current_validity"
        ],
        "properties": {
          "api_version": {
            "const": "1.0.0"
          },
          "mode": {
            "const": "demonstration"
          },
          "authoritative": {
            "const": false
          },
          "current_validity": {
            "const": "unknown"
          }
        }
      },
      "CheckRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "permit_number",
          "address"
        ],
        "properties": {
          "permit_number": {
            "oneOf": [
              {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9-]*$"
              },
              {
                "type": "integer",
                "minimum": 0
              }
            ]
          },
          "address": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "unit": {
            "type": "string",
            "maxLength": 64
          },
          "reference": {
            "type": "string",
            "maxLength": 100
          }
        }
      },
      "CheckResult": {
        "type": "object",
        "required": [
          "result",
          "current_validity",
          "passes_snapshot_check",
          "receipt_id",
          "checked_at",
          "request",
          "address_match",
          "permit",
          "message"
        ],
        "properties": {
          "reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "receipt_id": {
            "type": "string",
            "pattern": "^demo-[a-f0-9]{24}$"
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "current_validity": {
            "const": "unknown"
          },
          "normalized_address": {
            "type": "string"
          },
          "result": {
            "enum": [
              "active_in_snapshot",
              "inactive_in_snapshot",
              "address_mismatch",
              "unit_required",
              "unit_mismatch",
              "not_found",
              "needs_review"
            ]
          },
          "passes_snapshot_check": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "address_match": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "request": {
            "type": "object"
          },
          "permit": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "permit_number": {
                "type": "string"
              },
              "address": {
                "type": "string"
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status_in_snapshot": {
                "type": "string"
              },
              "issued": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "expiration": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Source": {
        "type": "object",
        "required": [
          "name",
          "as_of",
          "retrieved_at",
          "version",
          "url",
          "limitation"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "as_of": {
            "type": "string",
            "format": "date"
          },
          "retrieved_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "type": "string",
            "pattern": "^sha256:[a-f0-9]{64}$"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "limitation": {
            "type": "string"
          }
        }
      },
      "Error": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Envelope"
          },
          {
            "type": "object",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "object",
                "required": [
                  "code",
                  "message"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}
