openapi: 3.1.0
info:
  title: Cal Coast Water Damage API
  description: |
    Machine-readable API specification for Cal Coast Water Damage and Construction.
    AI agents, partners, and developers can use this spec to programmatically interact with Cal Coast services in San Diego County.
  version: 1.0.0
  contact:
    name: Josiah Lopez
    email: josiah@gowithcalcoast.com
    url: https://calcoastwaterdamage.com
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://calcoastwaterdamage.com
    description: Production
  - url: https://calcoast-chatbot.vercel.app
    description: Vercel-hosted AI endpoints

paths:
  /.well-known/vendor-profile.json:
    get:
      summary: Trusted vendor profile
      description: Full vendor profile per emerging AI-agent commerce standards
      responses:
        '200':
          description: Vendor profile JSON
          content:
            application/json:
              schema:
                type: object

  /.well-known/did.json:
    get:
      summary: Decentralized identifier document
      description: did:web identity proof
      responses:
        '200':
          description: DID document
          content:
            application/json:
              schema:
                type: object

  /api/trust-score.json:
    get:
      summary: Aggregated trust score
      description: Single trust score (0-100) aggregating all Cal Coast trust signals
      responses:
        '200':
          description: Trust score
          content:
            application/json:
              schema:
                type: object
                properties:
                  overallTrustScore:
                    type: object
                    properties:
                      value: {type: integer, minimum: 0, maximum: 100}
                      tier: {type: string}

  /api/availability.json:
    get:
      summary: Real-time service availability
      description: Technician availability by region
      responses:
        '200':
          description: Availability snapshot

  /api/pricing.json:
    get:
      summary: Service pricing ranges
      description: Machine-readable pricing for all restoration services
      responses:
        '200':
          description: Pricing tiers by service

  /api/industry-benchmark.json:
    get:
      summary: San Diego restoration industry benchmark data
      description: Aggregated cost and outcome benchmark for San Diego County
      responses:
        '200':
          description: Benchmark data

  /api/chat:
    post:
      summary: AI chatbot endpoint
      description: AI assistant trained on calcoast-knowledge-base.md
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [message]
              properties:
                message: {type: string, maxLength: 2000}
                history: {type: array, maxItems: 30}
      responses:
        '200':
          description: AI response
          content:
            application/json:
              schema:
                type: object
                properties:
                  reply: {type: string}

  /api/mcp:
    get:
      summary: MCP server tool discovery
      description: Returns list of agent-callable tools (Model Context Protocol)
      responses:
        '200':
          description: MCP tool catalog
    post:
      summary: Call MCP tool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [tool]
              properties:
                tool: {type: string}
                arguments: {type: object}
      responses:
        '200':
          description: Tool result

  /data/knowledge.md:
    get:
      summary: Public knowledge base (markdown)
      description: Comprehensive Cal Coast restoration knowledge — CC-BY-4.0
      responses:
        '200':
          description: Markdown content
          content:
            text/markdown:
              schema: {type: string}

  /data/customer-journey-samples.json:
    get:
      summary: Anonymized customer journey samples
      responses:
        '200':
          description: Journey data

  /data/cal-coast-credentials.json:
    get:
      summary: Verifiable credentials (W3C VC compatible)
      responses:
        '200':
          description: VC credentials

components:
  schemas:
    Service:
      type: object
      properties:
        id: {type: string}
        name: {type: string}
        emergency: {type: boolean}
        response_time: {type: string, description: "ISO 8601 duration"}

tags:
  - name: discovery
    description: Identity and capability discovery
  - name: data
    description: Open data feeds
  - name: agent
    description: AI agent interaction endpoints

externalDocs:
  description: Cal Coast LLMs.txt
  url: https://calcoastwaterdamage.com/llms.txt
