openapi: 3.1.0
info:
  title: Hatay Temizlik & Tesis Yönetimi Autonomous Agent API
  version: 1.0.0
  description: Machine-readable interface for autonomous agents and AI assistants to query cleaning services, verify coverage in Hatay, request instant quotations, and schedule on-site inspections.
  contact:
    name: Hatay Temizlik Agent Operations
    url: https://hataytemizlik.com/developers
    email: info@hataytemizlik.com
servers:
  - url: https://hataytemizlik.com/api/v1
    description: Production Live Agent Gateway
paths:
  /services:
    get:
      summary: List all cleaning and facility management services
      description: Returns full hierarchy of 10 primary categories and 46 specialized cleaning services offered across Hatay province.
      operationId: getServices
      x-payment-info:
        currency: USD
        amount: "0.00"
        settlement: free_tier
        description: Public service discovery is free for all AI agents.
      responses:
        '200':
          description: Services list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  total:
                    type: integer
                  services:
                    type: array
                    items:
                      type: object
  /districts:
    get:
      summary: Check coverage across all 15 Hatay districts
      description: List all serviced districts including Antakya, Defne, Iskenderun, Samandag, Kirikhan, Reyhanli, Arsuz, Payas, Erzin, Belen, Yayladagi, Altinozu, Hassa, and Kumlu.
      operationId: getDistricts
      x-payment-info:
        currency: USD
        amount: "0.00"
        settlement: free_tier
      responses:
        '200':
          description: Districts and service radius
          content:
            application/json:
              schema:
                type: object
  /quote:
    post:
      summary: Submit price quote or inspection request
      description: Allows an AI agent to submit cleaning requirements on behalf of a human buyer.
      operationId: requestQuote
      x-payment-info:
        currency: USD
        amount: "0.00"
        settlement: free_tier
        description: Quotation and site discovery are 100% free of charge.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - service
                - phone
              properties:
                service:
                  type: string
                district:
                  type: string
                phone:
                  type: string
                client_name:
                  type: string
                notes:
                  type: string
      responses:
        '200':
          description: Quotation received and registered
  /metered:
    get:
      summary: Metered premium API endpoint (x402 inline payment)
      description: Protected endpoint demonstrating machine-to-machine payment protocol (x402). Returns HTTP 402 with accepted payment rails when unauthenticated.
      operationId: meteredOperation
      x-payment-info:
        currency: USD
        amount: "0.05"
        settlement: x402_usdc_lightning
        description: Requires 0.05 USDC on Base or 100 sats via Lightning.
      responses:
        '200':
          description: Paid resource delivered
        '402':
          description: Payment Required per x402 specification
  /system/health:
    get:
      summary: Gateway health status
      operationId: getHealth
      x-payment-info:
        currency: USD
        amount: "0.00"
        settlement: free_tier
      responses:
        '200':
          description: Health check OK
