{
 "openapi": "3.1.0",
 "info": {
  "title": "TapSafely scam check API",
  "version": "1.0.0",
  "description": "Check messages and links for scam and phishing warning signs. Browser use requires Cloudflare Turnstile; server-to-server use needs an API key (contact us). Results are automated risk assessments, never proof that something is safe.",
  "contact": {
   "name": "A.I.T. Multiverse Consulting Ltd",
   "email": "hello@tapsafely.com",
   "url": "https://tapsafely.com/developers"
  },
  "termsOfService": "https://tapsafely.com/terms"
 },
 "servers": [
  {
   "url": "https://tapsafely.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-Api-Key"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  },
  "schemas": {
   "CheckRequest": {
    "type": "object",
    "required": [
     "kind"
    ],
    "properties": {
     "kind": {
      "type": "string",
      "enum": [
       "text",
       "url",
       "image"
      ]
     },
     "text": {
      "type": "string",
      "description": "Message text (kind=text)"
     },
     "url": {
      "type": "string",
      "description": "Link or domain (kind=url)"
     },
     "image": {
      "type": "string",
      "description": "Screenshot as a data: URL (kind=image)"
     },
     "turnstile": {
      "type": "string",
      "description": "Turnstile token (browser use only)"
     }
    }
   },
   "CheckResult": {
    "type": "object",
    "properties": {
     "score": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100
     },
     "level": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string",
        "enum": [
         "clear",
         "caution",
         "suspicious",
         "high"
        ]
       },
       "label": {
        "type": "string"
       },
       "headline": {
        "type": "string"
       }
      }
     },
     "summary": {
      "type": "string"
     },
     "flags": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "label": {
         "type": "string"
        },
        "detail": {
         "type": "string"
        },
        "weight": {
         "type": "number"
        }
       }
      }
     },
     "advice": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "category": {
      "type": "object"
     },
     "aiStatus": {
      "type": "string"
     },
     "disclaimer": {
      "type": "string"
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   }
  }
 },
 "paths": {
  "/api/check": {
   "post": {
    "operationId": "checkScam",
    "summary": "Check a message, link or screenshot",
    "security": [
     {
      "apiKey": []
     },
     {
      "bearer": []
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CheckRequest"
       },
       "example": {
        "kind": "text",
        "text": "Your parcel is on hold. Pay the 1.99 fee: https://example-redelivery.top"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Risk assessment",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CheckResult"
        }
       }
      }
     },
     "400": {
      "description": "Bad input",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Human check or API key required",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/weather": {
   "get": {
    "operationId": "scamWeather",
    "summary": "Trending scam types (last 7 days)",
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z]{2}$"
      },
      "description": "ISO country code, or omit for global"
     }
    ],
    "responses": {
     "200": {
      "description": "Trends",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/health": {
   "get": {
    "operationId": "health",
    "summary": "Service status",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/mcp": {
   "post": {
    "operationId": "mcp",
    "summary": "MCP server (Streamable HTTP, JSON-RPC 2.0)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "JSON-RPC response"
     }
    }
   }
  },
  "/a2a": {
   "post": {
    "operationId": "a2a",
    "summary": "A2A agent endpoint (JSON-RPC 2.0, message/send)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "JSON-RPC response"
     }
    }
   }
  }
 }
}