{"openapi":"3.1.0","info":{"title":"PermitStack (BYOK) API","version":"0.1.0","description":"PermitStack (BYOK) lets an AI assistant read your own PermitStack data through the PermitStack API with a key you supply (PermitStack API key). Read-only: 9 tools (search_permits, get_permit, get_permits_by_address, list_permit_events, get_property_history, get_property_by_parcel, search_contractors, get_contractor, find_systems_due_for_replacement). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-permitstack.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-permitstack/docs"},"termsOfService":"https://connectorbay.com/byok-permitstack/terms"},"servers":[{"url":"https://byok-permitstack.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-permitstack/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_permits":{"post":{"operationId":"search_permits","summary":"Search US building permits by location, address, parcel, category, status, property type, date, value or keyword. Return","description":"Search US building permits by location, address, parcel, category, status, property type, date, value or keyword. Returns permit number, status, category, address, parcel, description, estimated value, dates, contractor and jurisdiction. Use for \"Which roofing permits were issued in Tampa, FL in the last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code, for example 'FL'.","title":"State"},"city":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"City name, case-insensitive, for example 'Tampa'.","title":"City"},"zip_code":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Five-digit ZIP code.","title":"Zip Code"},"jurisdiction":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Permit jurisdiction name (partial, case-insensitive) as listed by PermitStack coverage, for example 'Tampa'.","title":"Jurisdiction"},"address":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Street address, partial and case-insensitive, for example '1600 Pennsylvania'.","title":"Address"},"parcel":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Parcel number or APN; punctuation is ignored.","title":"Parcel"},"category":{"anyOf":[{"enum":["new_construction","renovation","demolition","electrical","plumbing","mechanical","roofing","solar","battery","ev_charger","hvac","fire_alarm","sign","fence","pool","foundation","addition","interior_remodel","grading","other"],"type":"string"},{"type":"null"}],"default":null,"description":"Permit category.","title":"Category"},"status":{"anyOf":[{"enum":["filed","issued","in_progress","final","expired","cancelled","revoked","unknown"],"type":"string"},{"type":"null"}],"default":null,"description":"Permit status.","title":"Status"},"property_type":{"anyOf":[{"enum":["residential","commercial","industrial","multifamily","other"],"type":"string"},{"type":"null"}],"default":null,"description":"Property type.","title":"Property Type"},"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive text to find in the description, address or permit number (3 or more characters).","title":"Q"},"contractor_name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Contractor name, partial match.","title":"Contractor Name"},"date_after":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Keep permits issued or filed on or after this date, YYYY-MM-DD.","title":"Date After"},"date_before":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Keep permits issued or filed on or before this date, YYYY-MM-DD.","title":"Date Before"},"min_value":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Minimum estimated project value in US dollars.","title":"Min Value"},"max_value":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Maximum estimated project value in US dollars.","title":"Max Value"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"search_permitsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_permit":{"post":{"operationId":"get_permit","summary":"Get one building permit by its PermitStack id: status, category, address, parcel, description, estimated value, dates, c","description":"Get one building permit by its PermitStack id: status, category, address, parcel, description, estimated value, dates, contractor, jurisdiction and coordinates. Use for \"What are the details of permit 7f3c2a10-5b1e-4c55-9d2a-1c0b6a3e9f11\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"permit_id":{"description":"PermitStack permit id (the 'id' field of a permit record).","maxLength":200,"title":"Permit Id","type":"string"}},"required":["permit_id"],"title":"get_permitArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_permits_by_address":{"post":{"operationId":"get_permits_by_address","summary":"List every permit on file for a street address (partial match), newest records first, with status, category, valuation a","description":"List every permit on file for a street address (partial match), newest records first, with status, category, valuation and dates. Use for \"What permits have been pulled at 123 Main St\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"Street address to match, partial and case-insensitive, for example '123 Main St'.","maxLength":200,"title":"Address","type":"string"},"record_kind":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":"permit","description":"'permit' (default), a specific record kind, or 'all'.","title":"Record Kind"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["address"],"title":"get_permits_by_addressArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_permit_events":{"post":{"operationId":"list_permit_events","summary":"List permit change events (new permit, status change, issued, completed, expired) detected in the daily ingest, newest f","description":"List permit change events (new permit, status change, issued, completed, expired) detected in the daily ingest, newest first, filterable by place, category and type. Use for \"Which new solar permits were detected in Tampa recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_type":{"anyOf":[{"enum":["new_permit","status_change","issued","completed","expired"],"type":"string"},{"type":"null"}],"default":null,"description":"Event type to keep.","title":"Event Type"},"category":{"anyOf":[{"enum":["new_construction","renovation","demolition","electrical","plumbing","mechanical","roofing","solar","battery","ev_charger","hvac","fire_alarm","sign","fence","pool","foundation","addition","interior_remodel","grading","other"],"type":"string"},{"type":"null"}],"default":null,"description":"Permit category.","title":"Category"},"city":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"City name.","title":"City"},"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code.","title":"State"},"jurisdiction":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Jurisdiction name (partial).","title":"Jurisdiction"},"permit_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only events for this permit id.","title":"Permit Id"},"detected_after":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Keep events detected on or after this ISO date, YYYY-MM-DD.","title":"Detected After"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_permit_eventsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_property_history":{"post":{"operationId":"get_property_history","summary":"Get the construction history of an address: permit timeline, counts by category, contractors, total valuation and signal","description":"Get the construction history of an address: permit timeline, counts by category, contractors, total valuation and signals such as solar, roof, HVAC and pool age. An address with no permits returns found false. Use for \"What permits and roof, solar or HVAC work are on record for 123 Main St, Tampa, FL\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"Street address to look up, for example '123 Main St'.","maxLength":200,"title":"Address","type":"string"},"city":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"City, to tell identical street addresses apart.","title":"City"},"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code.","title":"State"},"zip":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"ZIP code (prefix-matched).","title":"Zip"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["address"],"title":"get_property_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_property_by_parcel":{"post":{"operationId":"get_property_by_parcel","summary":"Get the construction history of a parcel (APN): permit timeline, counts by category, contractors, total valuation and si","description":"Get the construction history of a parcel (APN): permit timeline, counts by category, contractors, total valuation and signals such as solar, roof, HVAC and pool age. Use for \"What permits are on record for parcel A-12-29-18-ZZZ-000001-00010.0 in Florida\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parcel":{"description":"Parcel number, APN or folio; dashes, dots and spaces are ignored.","maxLength":60,"title":"Parcel","type":"string"},"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code, to tell counties apart.","title":"State"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["parcel"],"title":"get_property_by_parcelArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_contractors":{"post":{"operationId":"search_contractors","summary":"Search permit-pulling contractors by name, location, specialty or licence number, ranked by activity score, with permit ","description":"Search permit-pulling contractors by name, location, specialty or licence number, ranked by activity score, with permit counts and licence details. Contact details are not returned. Use for \"Which roofing contractors in Tampa have pulled the most permits\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Contractor name, partial match.","title":"Name"},"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter state where the contractor pulls permits.","title":"State"},"city":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"City name.","title":"City"},"specialty":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Specialty tag such as solar, roofing or hvac.","title":"Specialty"},"license_number":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Exact state licence number, for example 'CBC1262595'.","title":"License Number"},"license_state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter state that issued the licence.","title":"License State"},"min_permits":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum total permits.","title":"Min Permits"},"min_score":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum activity score, 0 to 100.","title":"Min Score"},"sort":{"anyOf":[{"enum":["score","permits","recent"],"type":"string"},{"type":"null"}],"default":"score","description":"Sort order.","title":"Sort"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"search_contractorsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_contractor":{"post":{"operationId":"get_contractor","summary":"Get a contractor profile by id: name, licence, location, permit totals, first and last permit dates, specialties, recent","description":"Get a contractor profile by id: name, licence, location, permit totals, first and last permit dates, specialties, recent categories and average project value. Phone and email are not returned. Use for \"What is the permit history summary of contractor c1d2e3f4-0000-4000-8000-000000000001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contractor_id":{"description":"PermitStack contractor id (the 'id' of a contractor search result).","maxLength":200,"title":"Contractor Id","type":"string"}},"required":["contractor_id"],"title":"get_contractorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_systems_due_for_replacement":{"post":{"operationId":"find_systems_due_for_replacement","summary":"Find addresses whose most recent permit for a trade (roofing, HVAC, mechanical, solar, pool) is old enough that the syst","description":"Find addresses whose most recent permit for a trade (roofing, HVAC, mechanical, solar, pool) is old enough that the system is likely due for replacement, with nothing newer on file. Use for \"Which Tampa addresses had their last roofing permit 15 to 25 years ago\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"trade":{"description":"Trade to check.","enum":["roofing","hvac","mechanical","solar","pool"],"title":"Trade","type":"string"},"state":{"anyOf":[{"maxLength":2,"type":"string"},{"type":"null"}],"default":null,"description":"Two-letter US state code.","title":"State"},"city":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"City name.","title":"City"},"zip_code":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Five-digit ZIP code.","title":"Zip Code"},"jurisdiction":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Jurisdiction name (partial).","title":"Jurisdiction"},"min_age_years":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Override the trade's default minimum age in years.","title":"Min Age Years"},"max_age_years":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Override the trade's default maximum age in years.","title":"Max Age Years"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["trade"],"title":"find_systems_due_for_replacementArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}