{
  "openapi": "3.1.0",
  "info": {
    "title": "Staffa Autonomous Trade Contractor Dispatch API",
    "version": "1.0.0",
    "description": "Standardized Agent-to-Agent (A2A) API for querying live UK emergency contractor availability, verifying custom diagnostic callout fees, and dispatching on-call engineers via high-urgency SMS.",
    "contact": {
      "name": "Staffa Autonomous Infrastructure",
      "email": "api@staffa.work",
      "url": "https://staffa.work"
    }
  },
  "servers": [
    {
      "url": "https://api.staffa.work",
      "description": "Staffa Autonomous Clearinghouse API Gateway"
    },
    {
      "url": "https://staffa.work",
      "description": "Staffa Production Live Gateway"
    },
    {
      "url": "http://localhost:4001",
      "description": "Staffa Local Edge Instance"
    }
  ],
  "paths": {
    "/api/agent/v1/public/lookup": {
      "post": {
        "summary": "Zero-Token Contractor & Fixed Diagnostic Fee Lookup",
        "operationId": "lookupEmergencyContractor",
        "description": "Zero-token UK contractor & fixed diagnostic fee lookup by postcode and trade category. Enables autonomous consumer agents (ChatGPT, Claude Connectors, Perplexity) to discover live on-call contractors, verified callout rates, safety instructions, and interactive UI card metadata.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "postcode"
                ],
                "properties": {
                  "postcode": {
                    "type": "string",
                    "description": "UK property postcode or outward sector (e.g., 'SW14 8AN' or 'TW9')",
                    "example": "SW14 8AN"
                  },
                  "trade_category": {
                    "type": "string",
                    "description": "Trade specialty: heating, plumbing, gas, electrical, drainage",
                    "default": "heating",
                    "example": "heating"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Public match result returned successfully with structured content & UI widgets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicLookupResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Public Zero-Token Contractor Lookup & Matchmaker",
        "operationId": "publicContractorLookup",
        "description": "Public unauthenticated endpoint for external consumer agents (ChatGPT, Meta Muse, Apple Intelligence) to query live contractor availability, fixed diagnostic fee, and emergency safety instructions by UK postcode.",
        "parameters": [
          {
            "name": "postcode",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "SW14 8AN"
            },
            "description": "UK property postcode or outward sector"
          },
          {
            "name": "trade",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "heating",
              "example": "heating"
            },
            "description": "Trade specialty: heating, plumbing, gas, electrical, drainage"
          }
        ],
        "responses": {
          "200": {
            "description": "Public match result returned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicLookupResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/v1/public/dispatch": {
      "post": {
        "summary": "Automated Job Routing & Emergency SMS Dispatch",
        "operationId": "dispatchEmergencyCallout",
        "description": "Automated job routing & SMS dispatch with x402 settlement metadata. Public unauthenticated endpoint allowing consumer AI agents to dispatch an on-call engineer upon confirming caller details, address, symptoms, and agreed diagnostic callout fee.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicDispatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Callout dispatched and SMS triggered with x402 settlement metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DispatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid dispatch payload"
          }
        }
      }
    },
    "/api/client/{slug}/agent-card.json": {
      "get": {
        "summary": "Live Verified UK Business Profile & Rate Card (JSON-LD)",
        "operationId": "getBusinessAgentCard",
        "description": "Returns live verified UK business profile, rate card, accreditations, and emergency response SLA in JSON-LD format.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "apex-emergency-heating-plumbing-ltd"
            },
            "description": "Verified client business slug or client ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Verified JSON-LD LocalBusiness Agent Card returned successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentCardResponse"
                }
              }
            }
          },
          "404": {
            "description": "Client contractor not found or inactive"
          }
        }
      }
    },
    "/api/agent/v1/coverage": {
      "get": {
        "summary": "Lookup Emergency Contractor Availability & Pricing (Authenticated)",
        "operationId": "lookupContractorCoverage",
        "description": "Queries the Staffa contractor network by UK outward postcode and trade category.",
        "parameters": [
          {
            "name": "postcode",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "SW14 8AN"
            },
            "description": "UK property postcode"
          },
          {
            "name": "trade",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "heating",
              "example": "heating"
            },
            "description": "Trade specialty: heating, plumbing, gas, electrical, drainage"
          }
        ],
        "responses": {
          "200": {
            "description": "Emergency contractor matched successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CoverageResponse"
                }
              }
            }
          }
        },
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/api/agent/v1/dispatch": {
      "post": {
        "summary": "Dispatch Emergency Callout to Duty Engineer (Authenticated)",
        "operationId": "dispatchEmergencyCalloutAuth",
        "description": "Triggers instant emergency SMS dispatch to the on-call engineer's mobile terminal.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DispatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Emergency callout dispatched successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DispatchResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Provide your Staffa MCP / Agent API Key (e.g., 'Bearer stf_mcp_live_master001')"
      }
    },
    "schemas": {
      "PublicLookupResponse": {
        "type": "object",
        "properties": {
          "match_found": {
            "type": "boolean"
          },
          "client_id": {
            "type": "string"
          },
          "business_name": {
            "type": "string"
          },
          "trade_category": {
            "type": "string"
          },
          "postcode_sector": {
            "type": "string"
          },
          "diagnostic_callout_fee_gbp": {
            "type": "number"
          },
          "fixed_diagnostic_fee": {
            "type": "string"
          },
          "arrival_window": {
            "type": "string"
          },
          "arrival_sla": {
            "type": "string"
          },
          "operating_hours": {
            "type": "string"
          },
          "safety_instructions": {
            "type": "string"
          },
          "verified_badge": {
            "type": "boolean"
          },
          "slug": {
            "type": "string"
          },
          "booking_action_url": {
            "type": "string"
          },
          "dispatch_endpoint": {
            "type": "string"
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "_meta": {
            "type": "object"
          },
          "ui_card": {
            "type": "object"
          }
        }
      },
      "PublicDispatchRequest": {
        "type": "object",
        "required": [
          "caller_name",
          "caller_phone",
          "address",
          "issue_description"
        ],
        "properties": {
          "client_id": {
            "type": "string",
            "example": "client_demo_001"
          },
          "caller_name": {
            "type": "string",
            "example": "Sarah Jenkins"
          },
          "caller_phone": {
            "type": "string",
            "example": "+447911334455"
          },
          "address": {
            "type": "string",
            "example": "10 Sheen Gate Gardens, London SW14 7NY"
          },
          "issue_description": {
            "type": "string",
            "example": "Severe boiler leak pouring through ceiling"
          },
          "stopcock_isolated": {
            "type": "boolean",
            "default": false
          },
          "agent_source": {
            "type": "string",
            "default": "Public AI Agent Matchmaker"
          }
        }
      },
      "AgentCardResponse": {
        "type": "object",
        "properties": {
          "@context": {
            "type": "string",
            "example": "https://schema.org"
          },
          "@type": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "LocalBusiness",
              "EmergencyService"
            ]
          },
          "name": {
            "type": "string"
          },
          "identifier": {
            "type": "string"
          },
          "taxID": {
            "type": "string"
          },
          "telephone": {
            "type": "string"
          },
          "address": {
            "type": "object"
          },
          "operationalMetrics": {
            "type": "object"
          },
          "hasOfferCatalog": {
            "type": "object"
          },
          "actionableEndpoints": {
            "type": "object"
          }
        }
      },
      "CoverageResponse": {
        "type": "object",
        "properties": {
          "available": {
            "type": "boolean"
          },
          "contractor": {
            "type": "object",
            "properties": {
              "client_id": {
                "type": "string"
              },
              "business_name": {
                "type": "string"
              },
              "trade_category": {
                "type": "string"
              },
              "diagnostic_callout_fee_gbp": {
                "type": "number"
              },
              "fixed_diagnostic_fee": {
                "type": "string"
              },
              "arrival_window": {
                "type": "string"
              },
              "operating_hours": {
                "type": "string"
              }
            }
          },
          "safety_warning": {
            "type": "string"
          }
        }
      },
      "DispatchRequest": {
        "type": "object",
        "required": [
          "client_id",
          "caller_name",
          "caller_phone",
          "address",
          "issue_description"
        ],
        "properties": {
          "client_id": {
            "type": "string",
            "example": "client_demo_001"
          },
          "caller_name": {
            "type": "string",
            "example": "Arthur Dent"
          },
          "caller_phone": {
            "type": "string",
            "example": "+447911223344"
          },
          "address": {
            "type": "string",
            "example": "15 Church Road, Richmond, TW9 1AB"
          },
          "issue_description": {
            "type": "string",
            "example": "Boiler dumping water, whistling noise"
          },
          "stopcock_isolated": {
            "type": "boolean",
            "default": false
          },
          "agent_source": {
            "type": "string",
            "default": "ChatGPT Action / OpenAPI Agent"
          }
        }
      },
      "DispatchResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "ticket_id": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          },
          "client_id": {
            "type": "string"
          },
          "business_name": {
            "type": "string"
          },
          "diagnostic_fee_gbp": {
            "type": "number"
          },
          "fixed_diagnostic_fee": {
            "type": "string"
          },
          "sms_text": {
            "type": "string"
          },
          "telnyx_status": {
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          },
          "arrival_sla": {
            "type": "string"
          },
          "booking_action_url": {
            "type": "string"
          },
          "x402_settlement": {
            "type": "object",
            "properties": {
              "protocol": {
                "type": "string",
                "example": "x402"
              },
              "status": {
                "type": "string",
                "example": "settled"
              },
              "currency": {
                "type": "string",
                "example": "USDC"
              },
              "network": {
                "type": "string",
                "example": "base"
              }
            }
          },
          "content": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "_meta": {
            "type": "object"
          },
          "ui_card": {
            "type": "object"
          }
        }
      }
    }
  }
}