{
  "openapi": "3.1.0",
  "info": {
    "title": "Permits API",
    "version": "1.0.0",
    "description": "Building-permit leads for Israel.\n\n**Auth:** `Authorization: Bearer pk_…`\n**Rate limit:** per-key requests/minute (429 when exceeded).\n\nHebrew guide: see the Docusaurus docs site (`apps/docs`).\nעברית: מדריך מלא באתר התיעוד (Docusaurus)."
  },
  "servers": [
    {
      "url": "/",
      "description": "This API host"
    }
  ],
  "tags": [
    {
      "name": "Applications",
      "description": "Permit applications / leads"
    },
    {
      "name": "Feed",
      "description": "Saved-filter feed and daily webhook"
    },
    {
      "name": "Meta",
      "description": "Health"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pk_",
        "description": "API key shown once at creation / rotation."
      }
    },
    "schemas": {
      "Lead": {
        "type": "object",
        "description": "Building-permit application as returned in lists, feed, and webhooks.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "requestNumber": {
            "type": "string",
            "nullable": true
          },
          "permitNumber": {
            "type": "string",
            "nullable": true
          },
          "buildingFile": {
            "type": "string",
            "nullable": true
          },
          "infoRequestNumber": {
            "type": "string",
            "nullable": true
          },
          "linkedPermitNumber": {
            "type": "string",
            "nullable": true
          },
          "street": {
            "type": "string",
            "nullable": true
          },
          "houseNumber": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "neighborhood": {
            "type": "string",
            "nullable": true
          },
          "gush": {
            "type": "string",
            "nullable": true
          },
          "helka": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "description": "GeoJSON point when known",
            "nullable": true
          },
          "stage": {
            "type": "string",
            "enum": [
              "submitted",
              "decision",
              "permit",
              "excavation",
              "site"
            ],
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "decision": {
            "type": "string",
            "enum": [
              "approve",
              "approve_conditions",
              "reject",
              "defer",
              "other"
            ],
            "nullable": true
          },
          "workType": {
            "type": "string",
            "enum": [
              "excavation_shoring",
              "new_building",
              "demolish_rebuild",
              "addition",
              "alterations",
              "other"
            ],
            "nullable": true
          },
          "classification": {
            "type": "string",
            "nullable": true
          },
          "flags": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "tama38",
                "urban_renewal",
                "demolition",
                "seismic"
              ]
            }
          },
          "trades": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "housingUnits": {
            "type": "integer",
            "nullable": true
          },
          "floors": {
            "type": "integer",
            "nullable": true
          },
          "builtAreaSqm": {
            "type": "number",
            "nullable": true
          },
          "scope": {
            "type": "string",
            "nullable": true
          },
          "estimatedValue": {
            "type": "number",
            "nullable": true,
            "description": "Estimated value in ILS"
          },
          "submittedAt": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "decisionAt": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "permitIssuedAt": {
            "type": "string",
            "format": "date",
            "nullable": true
          },
          "sourceUrl": {
            "type": "string",
            "nullable": true
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "Filters": {
        "type": "object",
        "description": "Saved lead filter on the API key (same fields as list query filters).",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "excavation_shoring",
              "new_building",
              "demolish_rebuild",
              "addition",
              "alterations",
              "other",
              "new"
            ],
            "description": "Work type. `new` = excavation_shoring + new_building + demolish_rebuild."
          },
          "stage": {
            "type": "string",
            "enum": [
              "submitted",
              "decision",
              "permit",
              "excavation",
              "site"
            ],
            "description": "Pipeline stage reached."
          },
          "decision": {
            "type": "string",
            "enum": [
              "approve",
              "approve_conditions",
              "reject",
              "defer",
              "other",
              "open"
            ],
            "description": "`open` = anything except reject."
          },
          "flag": {
            "type": "string",
            "enum": [
              "tama38",
              "urban_renewal",
              "demolition",
              "seismic"
            ],
            "description": "Must include this flag."
          },
          "trade": {
            "type": "string",
            "description": "Trade/specialty mentioned on the application."
          },
          "q": {
            "type": "string",
            "minLength": 2,
            "maxLength": 200,
            "description": "Semantic search over the description. When set, results are ranked by similarity and not cursor-paginated."
          },
          "city": {
            "type": "string",
            "description": "Partial, case-insensitive city match."
          },
          "neighborhood": {
            "type": "string",
            "description": "Partial, case-insensitive neighborhood match."
          },
          "minUnits": {
            "type": "integer",
            "minimum": 1,
            "description": "Minimum housing units. Rows without units are excluded."
          },
          "minValue": {
            "type": "number",
            "minimum": 1,
            "description": "Minimum estimated value (ILS). Rows without a value are excluded."
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "Meta"
        ],
        "summary": "Health check",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/applications": {
      "get": {
        "tags": [
          "Applications"
        ],
        "summary": "List applications",
        "description": "Cursor-paginated by `firstSeenAt` desc. With `q`, ranked by semantic similarity and `nextCursor` is always null.",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "excavation_shoring",
                "new_building",
                "demolish_rebuild",
                "addition",
                "alterations",
                "other",
                "new"
              ]
            },
            "description": "Work type. `new` = excavation_shoring + new_building + demolish_rebuild."
          },
          {
            "name": "stage",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "submitted",
                "decision",
                "permit",
                "excavation",
                "site"
              ]
            },
            "description": "Pipeline stage reached."
          },
          {
            "name": "decision",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "approve",
                "approve_conditions",
                "reject",
                "defer",
                "other",
                "open"
              ]
            },
            "description": "`open` = anything except reject."
          },
          {
            "name": "flag",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "tama38",
                "urban_renewal",
                "demolition",
                "seismic"
              ]
            },
            "description": "Must include this flag."
          },
          {
            "name": "trade",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Trade/specialty mentioned on the application."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "description": "Semantic search over the description. When set, results are ranked by similarity and not cursor-paginated."
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Partial, case-insensitive city match."
          },
          {
            "name": "neighborhood",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Partial, case-insensitive neighborhood match."
          },
          {
            "name": "minUnits",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Minimum housing units. Rows without units are excluded."
          },
          {
            "name": "minValue",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 1
            },
            "description": "Minimum estimated value (ILS). Rows without a value are excluded."
          },
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "firstSeenAt ≥ since"
          },
          {
            "name": "updatedSince",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "updatedAt ≥ updatedSince"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque cursor from a previous `nextCursor` (ignored when `q` is set)."
          }
        ],
        "responses": {
          "200": {
            "description": "Page of leads",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Lead"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/applications/{id}": {
      "get": {
        "tags": [
          "Applications"
        ],
        "summary": "Get application",
        "description": "Full lead plus applicants, professionals, events, and linked construction sites.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lead detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Lead"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "conditions": {
                              "nullable": true
                            },
                            "estimate": {
                              "nullable": true
                            },
                            "applicants": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            },
                            "professionals": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            },
                            "events": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            },
                            "sites": {
                              "type": "array",
                              "items": {
                                "type": "object"
                              }
                            }
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/feed": {
      "get": {
        "tags": [
          "Feed"
        ],
        "summary": "Saved-filter feed",
        "description": "Uses the API key's saved filters. Returns newest matches since `since` (default 7 days), most valuable first, max 200.",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Defaults to 7 days ago."
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered leads",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "filters": {
                      "$ref": "#/components/schemas/Filters"
                    },
                    "since": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Lead"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid since",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "dailyFeed": {
      "post": {
        "tags": [
          "Feed"
        ],
        "summary": "Daily lead webhook",
        "description": "Once per day the worker POSTs new applications (firstSeenAt after the last successful delivery) that match the key's saved filter. HTTPS only. Empty days still advance the watermark with no POST when there are zero matches.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "since": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "until": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "filters": {
                    "$ref": "#/components/schemas/Filters"
                  },
                  "applications": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/Lead"
                    }
                  }
                },
                "required": [
                  "since",
                  "until",
                  "filters",
                  "applications"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx acknowledges delivery"
          }
        }
      }
    }
  }
}
