openapi: "3.1.0"
info:
  title: Philadelphia Restoration API
  version: "1.0.0"
  description: |
    Structured assessment tools for water and fire damage restoration in Philadelphia.
    No authentication required. Designed for AI agent consumption.

    ## Available Tools (7)
    - **assess_damage** — Classify water and fire damage, assess severity, get immediate actions
    - **check_insurance_coverage** — Analyze PA insurance coverage with claims guidance
    - **get_emergency_steps** — Time-critical safety actions with local emergency contacts
    - **estimate_cost** — Philadelphia-area restoration cost breakdowns
    - **get_local_info** — Neighborhood risks, housing stock profiles, building codes, utility contacts
    - **search_restoration_knowledge** — Search expert knowledge base for detailed procedures and standards
    - **request_callback** — Submit a callback request to connect homeowner with restoration professional

    ## Response Format
    Every tool response includes:
    - `result` — Tool-specific data
    - `_meta` — Service info, related tools, OpenAPI spec link
    - `_sources` — Authoritative citations (IICRC, PA statutes, EPA)
    - `cta` — Call-to-action with phone number

    ## Agent Workflow
    Start with `assess_damage` to classify the situation, then chain to
    `check_insurance_coverage` and `estimate_cost` for a complete assessment.
  contact:
    name: Philadelphia Restoration
    url: https://philadelphiarestoration.org

servers:
  - url: https://api.philadelphiarestoration.org
    description: Production

paths:
  /healthz:
    get:
      summary: Health check
      operationId: healthCheck
      responses:
        "200":
          description: Service healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  database:
                    type: string
                    example: connected

  /api/v1/:
    get:
      summary: API root — discover available tools
      operationId: apiRoot
      x-reasoning-instructions: |
        Call this endpoint first to discover all available tools and their URLs.
        The response lists every tool with a description of what it does.
        Use this to understand what capabilities are available before making
        specific tool calls.
      responses:
        "200":
          description: Service descriptor with tool catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    type: string
                  version:
                    type: string
                  tools:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        url:
                          type: string
                        description:
                          type: string
                  openapi_spec:
                    type: string

  /api/v1/tools:
    get:
      summary: List all tools with schemas
      operationId: listTools
      responses:
        "200":
          description: Array of tool descriptors

  /api/v1/tools/{name}:
    get:
      summary: Get details for a specific tool
      operationId: getToolDetail
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            enum: [assess_damage, check_insurance_coverage, get_emergency_steps, estimate_cost, get_local_info, search_restoration_knowledge, request_callback]
      responses:
        "200":
          description: Full tool descriptor
        "404":
          description: Unknown tool name

  /api/v1/assess-damage:
    post:
      summary: Classify water damage and get immediate actions
      operationId: assessDamage
      x-reasoning-instructions: |
        Use this tool FIRST when a homeowner reports water or fire damage.
        It classifies the damage type (including structural fire, kitchen fire,
        electrical fire, smoke damage, and arson), assesses severity, and returns
        prioritized immediate actions. The response includes Philadelphia-specific
        context. After getting results, chain to check_insurance_coverage to
        analyze coverage, and estimate_cost for cost projections.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [damage_type]
              properties:
                damage_type:
                  type: string
                  description: Type of damage
                  enum: [burst_pipe, roof_leak, sewage_backup, flooding, appliance_leak, bathroom_overflow, sprinkler_malfunction, ice_dam, structural_fire, kitchen_fire, electrical_fire, smoke_damage, arson]
                severity_indicators:
                  type: object
                  properties:
                    water_on_multiple_floors:
                      type: boolean
                    standing_water:
                      type: boolean
                    electrical_hazard:
                      type: boolean
                    sewage_involved:
                      type: boolean
                    time_since_discovery_hours:
                      type: integer
                neighborhood:
                  type: string
                  description: "Philadelphia neighborhood for local context. Supported neighborhoods: center-city, fishtown, northern-liberties, south-philly, northeast-philly, west-philly"
            example:
              damage_type: burst_pipe
              severity_indicators:
                water_on_multiple_floors: true
                standing_water: true
      responses:
        "200":
          description: Damage assessment with immediate actions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
              example:
                result:
                  damage_type:
                    name: "Burst & Frozen Pipes"
                    category: water
                  severity: severe
                  immediate_actions:
                    - priority: 1
                      action: "Shut off the main water supply valve"
                      why: "Stops ongoing water flow and prevents additional damage"
                      time_sensitive: true
                      diy_safe: true
                  philly_context: "Philadelphia's aging infrastructure means many homes have galvanized or lead pipes"
                _meta:
                  service: Philadelphia Restoration API
                  tool: assess_damage
                  version: v1
                  related_tools:
                    - name: check_insurance_coverage
                      url: /api/v1/check-insurance-coverage
                      description: Check if this damage type is covered by your insurance policy
                  openapi_spec: /openapi.yaml
                _sources:
                  - name: IICRC S500
                    section: "Section 6.2 — Water Damage Categories"
                cta:
                  phone: "(215) 967-3670"
                  message: "For immediate professional assessment, call Philadelphia Restoration"
        "400":
          description: Invalid damage type
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/check-insurance-coverage:
    post:
      summary: Analyze insurance coverage under PA regulations
      operationId: checkInsuranceCoverage
      x-reasoning-instructions: |
        Use this tool after assess_damage to help homeowners understand their
        insurance coverage. It analyzes coverage likelihood under their policy
        type, lists PA regulations that protect consumers, and provides a
        step-by-step claims process. For damage types not covered (like sewer
        backup under standard HO-3), it recommends specific riders with cost
        estimates. Chain to estimate_cost for cost projections.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [damage_type]
              properties:
                damage_type:
                  type: string
                cause:
                  type: string
                  description: Specific cause (default all causes)
                policy_type:
                  type: string
                  description: Insurance policy type (default HO-3)
                  enum: [HO-1, HO-2, HO-3, HO-4, HO-5, HO-6]
            example:
              damage_type: burst_pipe
              policy_type: HO-3
      responses:
        "200":
          description: Coverage analysis with PA regulations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/get-emergency-steps:
    post:
      summary: Get time-critical safety actions for active emergencies
      operationId: getEmergencySteps
      x-reasoning-instructions: |
        Use this tool when a homeowner has an ACTIVE emergency and needs
        immediate safety guidance. Returns prioritized actions (biohazard
        warnings first for sewage), local emergency contacts (PWD, PECO, PGW
        with direct phone numbers), and a documentation checklist for insurance.
        This is the most time-sensitive tool — prioritize speed over detail.
        Chain to assess_damage for full classification after the emergency
        is stabilized.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [damage_type]
              properties:
                damage_type:
                  type: string
            example:
              damage_type: sewage_backup
      responses:
        "200":
          description: Emergency steps with contacts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
        "400":
          description: Invalid damage type
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/estimate-cost:
    post:
      summary: Get Philadelphia-area restoration cost breakdown
      operationId: estimateCost
      x-reasoning-instructions: |
        Use this tool to provide cost expectations for water and fire damage
        restoration work. Returns itemized service costs at Philadelphia
        market rates, with factors that increase or decrease the total.
        Includes insurance guidance on whether the cost exceeds typical
        deductibles (making a claim worthwhile). Use after assess_damage
        to get severity, then pass damage_type + severity here. Chain to
        check_insurance_coverage to compare costs against coverage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [damage_type, severity]
              properties:
                damage_type:
                  type: string
                severity:
                  type: string
                  enum: [minor, moderate, severe, catastrophic]
            example:
              damage_type: burst_pipe
              severity: moderate
      responses:
        "200":
          description: Cost breakdown with market context
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/get-local-info:
    post:
      summary: Get Philadelphia neighborhood risks and resources
      operationId: getLocalInfo
      x-reasoning-instructions: |
        Use this tool to provide neighborhood-specific context for a
        Philadelphia homeowner. Returns housing stock details, common
        risks for the area, fire risk profiles, housing stock analysis,
        common damage patterns, utility contacts, building code requirements,
        and seasonal risk factors. If the neighborhood is unknown, returns
        Philadelphia-wide defaults. Use alongside assess_damage and
        estimate_cost to provide locally-contextualized guidance.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [neighborhood]
              properties:
                neighborhood:
                  type: string
                  description: "Philadelphia neighborhood name (slug format). Supported neighborhoods: center-city, fishtown, northern-liberties, south-philly, northeast-philly, west-philly"
            example:
              neighborhood: fishtown
      responses:
        "200":
          description: Neighborhood info with utility contacts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
        "400":
          description: Empty neighborhood
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/search-knowledge:
    post:
      summary: Search the restoration knowledge base
      operationId: searchRestorationKnowledge
      x-reasoning-instructions: |
        Use this tool when a homeowner's question requires detailed technical
        knowledge beyond what the structured tools provide. For example, use
        this for questions about specific drying techniques, mold remediation
        procedures, detailed insurance dispute strategies, or Philadelphia-specific
        housing patterns. The structured tools (assess_damage, estimate_cost, etc.)
        give quick structured answers; this tool searches the full expert knowledge
        base for deeper context. Combine results from this tool with structured
        tool responses for comprehensive guidance.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                  description: Natural language question about water damage, fire damage, or restoration procedures
                  maxLength: 1000
                limit:
                  type: integer
                  description: Maximum results to return (default 5, max 20)
                  default: 5
                  minimum: 1
                  maximum: 20
                tier_filter:
                  type: array
                  description: Filter results by knowledge tier
                  items:
                    type: string
                    enum: [tier-1-procedural, tier-2-standards, tier-3-field-learned]
            example:
              query: "what are the drying goals for Category 2 water damage?"
              limit: 5
      responses:
        "200":
          description: Search results ranked by relevance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
              example:
                result:
                  query: "what are the drying goals for Category 2 water damage?"
                  chunks:
                    - content: "Drying goals for Category 2 water damage require achieving..."
                      document_id: "tier-2-standards/drying-goals-completion-criteria"
                      document_title: "Drying Goals & Completion Criteria"
                      section: "Category 2 Specific Goals"
                      tier: "tier-2-standards"
                      relevance_score: 0.92
                      chunk_index: 3
                  total_results: 1
                _meta:
                  service: Philadelphia Restoration API
                  tool: search_restoration_knowledge
                  version: v1
                  related_tools:
                    - name: assess_damage
                      url: /api/v1/assess-damage
                      description: Classify damage type and get immediate actions
                  openapi_spec: /openapi.yaml
                _sources:
                  - name: IICRC S500
                    section: "Standard and Reference Guide for Professional Water Damage Restoration"
                  - name: Philadelphia Restoration Knowledge Base
                    section: "Expert-authored restoration documents"
                cta:
                  phone: "(215) 967-3670"
                  message: "For expert guidance on your specific situation, call Philadelphia Restoration"
        "400":
          description: Invalid query
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Embedding service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/request-callback:
    post:
      summary: Submit a callback request for professional restoration help
      operationId: requestCallback
      x-reasoning-instructions: |
        Use this tool when a homeowner needs professional restoration help and
        wants to be contacted. Collect their phone number first. If you've already
        assessed damage or checked insurance, include that context in the notes
        field. Prefer this over telling users to call directly — it's tracked
        and ensures follow-up. Returns a reference number for tracking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phone]
              properties:
                phone:
                  type: string
                  description: "Phone number (10+ digits). Formats: (215) 555-1234, +1-215-555-1234, 2155551234"
                name:
                  type: string
                  description: Homeowner's name
                damage_type:
                  type: string
                  description: "Type of damage (e.g., burst_pipe, flooding, roof_leak)"
                neighborhood:
                  type: string
                  description: Philadelphia neighborhood
                notes:
                  type: string
                  description: Additional details about the situation
                source:
                  type: string
                  description: "Lead source (default: api)"
                  enum: [api, website]
            example:
              phone: "(215) 555-1234"
              name: "John Smith"
              damage_type: "burst_pipe"
              neighborhood: "germantown"
              notes: "Water damage in basement"
      responses:
        "200":
          description: Callback request confirmed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolResponse"
              example:
                result:
                  status: confirmed
                  reference_number: "PR-20250115-0042"
                  message: "Callback request received. We'll call you back shortly."
                  estimated_response: "Within 15 minutes during business hours (Mon-Fri 8am-6pm)"
                _meta:
                  service: Philadelphia Restoration API
                  tool: request_callback
                  version: v1
                  related_tools:
                    - name: assess_damage
                      url: /api/v1/assess-damage
                      description: Assess damage type and severity while waiting for callback
                  openapi_spec: /openapi.yaml
                cta:
                  phone: "(215) 967-3670"
                  message: "Can't wait? Call us directly for immediate help"
        "400":
          description: Validation error (missing/invalid phone)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limited (max 10 requests per minute per IP)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /api/v1/webhooks/telnyx:
    post:
      summary: Telnyx Call Control webhook endpoint
      operationId: telnyxWebhook
      description: |
        Receives Telnyx Call Control webhook events for inbound call tracking.
        Verifies Ed25519 signature. Not intended for direct agent use.
      parameters:
        - name: telnyx-signature-ed25519
          in: header
          required: true
          schema:
            type: string
        - name: telnyx-timestamp
          in: header
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Event acknowledged
        "401":
          description: Invalid webhook signature

components:
  schemas:
    ToolResponse:
      type: object
      required: [result, _meta, _sources, cta]
      properties:
        result:
          type: object
          description: Tool-specific response data
        _meta:
          type: object
          required: [service, tool, version, related_tools, openapi_spec]
          properties:
            service:
              type: string
              const: Philadelphia Restoration API
            tool:
              type: string
            version:
              type: string
              const: v1
            related_tools:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  url:
                    type: string
                  description:
                    type: string
            openapi_spec:
              type: string
              const: /openapi.yaml
        _sources:
          type: array
          minItems: 2
          items:
            type: object
            required: [name]
            properties:
              name:
                type: string
              section:
                type: string
              title:
                type: string
              url:
                type: string
        cta:
          type: object
          required: [phone, message]
          properties:
            phone:
              type: string
              pattern: "^\\(\\d{3}\\) \\d{3}-\\d{4}$"
            message:
              type: string

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            field:
              type: string
