{
  "openapi": "3.1.0",
  "info": {
    "title": "SanctionsChecker.org API",
    "version": "1.0.0",
    "description": "Screen names against PEP databases (Denmark, Faroe Islands, Greenland), global sanctions lists (EU, OFAC, UN, UK, SECO), and AI-powered adverse media coverage.",
    "contact": {
      "name": "SanctionsChecker Support",
      "email": "support@sanctionschecker.org",
      "url": "https://sanctionschecker.org"
    },
    "license": { "name": "Proprietary" }
  },
  "servers": [
    {
      "url": "https://api.sanctionschecker.org/functions/v1",
      "description": "Production"
    }
  ],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Provide your App ID as the bearer token. Example: `Authorization: Bearer YOUR_APP_ID`. Create an App ID at https://sanctionschecker.org/dashboard/app-ids."
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "required": ["success", "error", "request_id", "timestamp"],
        "properties": {
          "success": { "type": "boolean", "enum": [false] },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "METHOD_NOT_ALLOWED",
                  "UNAUTHORIZED",
                  "INVALID_APP_ID",
                  "INVALID_REQUEST",
                  "SERVER_CONFIGURATION_ERROR",
                  "UPSTREAM_ERROR",
                  "INTERNAL_ERROR"
                ]
              },
              "message": { "type": "string" },
              "details": { "type": "string" }
            }
          },
          "request_id": { "type": "string", "format": "uuid" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "PEPMatch": {
        "type": "object",
        "properties": {
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }] },
          "name": { "type": "string", "nullable": true },
          "surname": { "type": "string", "nullable": true },
          "position": { "type": "string", "nullable": true },
          "date_of_birth": { "type": "string", "nullable": true },
          "added_at": { "type": "string", "format": "date-time" },
          "database": {
            "type": "string",
            "enum": ["PEP Denmark", "PEP Faroe Islands", "PEP Greenland"]
          },
          "match_score": { "type": "number" },
          "match_type": { "type": "string", "enum": ["exact", "fuzzy"] }
        }
      },
      "SanctionsMatch": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string", "nullable": true },
          "entity_type": { "type": "string", "nullable": true },
          "date_of_birth": { "type": "string", "nullable": true },
          "nationality": { "type": "string", "nullable": true },
          "address": { "type": "string", "nullable": true },
          "database": {
            "type": "string",
            "enum": ["EU Sanctions", "OFAC Sanctions", "UK Sanctions", "UN Sanctions", "SECO Sanctions"]
          },
          "match_score": { "type": "number" },
          "match_type": { "type": "string", "enum": ["exact", "fuzzy"] },
          "sanctions_details": { "type": "object", "additionalProperties": true }
        }
      },
      "AdverseMediaMatch": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "title": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "database": { "type": "string", "enum": ["Adverse Media"] },
          "match_score": { "type": "number" },
          "match_type": { "type": "string", "enum": ["adverse_media"] },
          "adverse_media_details": {
            "type": "object",
            "properties": {
              "summary": { "type": "string" },
              "confidence_score": { "type": "number" },
              "source_type": { "type": "string", "enum": ["news", "official", "blog", "social", "unknown"] },
              "publication_date": { "type": "string", "nullable": true },
              "snippet": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/pep-check": {
      "post": {
        "summary": "Screen a name against PEP databases",
        "operationId": "pepCheck",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "description": "Full name to screen.", "example": "Mette Frederiksen" },
                  "match_type": {
                    "type": "string",
                    "enum": ["exact", "fuzzy"],
                    "default": "exact",
                    "description": "exact = all terms must appear as complete words; fuzzy = all terms must appear anywhere in the name."
                  },
                  "external_ref": {
                    "type": "string",
                    "description": "Your internal reference (e.g. customer or case ID). Logged for audit and lookup."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Screening completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "enum": [true] },
                    "matches": { "type": "array", "items": { "$ref": "#/components/schemas/PEPMatch" } },
                    "total_matches": { "type": "integer" },
                    "query": { "type": "string" },
                    "match_type": { "type": "string", "enum": ["exact", "fuzzy"] },
                    "request_id": { "type": "string", "format": "uuid" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }
        }
      }
    },
    "/sanctions-check": {
      "post": {
        "summary": "Screen a name against global sanctions lists",
        "operationId": "sanctionsCheck",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "example": "John Smith" },
                  "match_type": { "type": "string", "enum": ["exact", "fuzzy"], "default": "exact" },
                  "external_ref": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Screening completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "enum": [true] },
                    "matches": { "type": "array", "items": { "$ref": "#/components/schemas/SanctionsMatch" } },
                    "total_matches": { "type": "integer" },
                    "query": { "type": "string" },
                    "match_type": { "type": "string", "enum": ["exact", "fuzzy"] },
                    "request_id": { "type": "string", "format": "uuid" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }
        }
      }
    },
    "/adverse-media-check": {
      "post": {
        "summary": "Screen a name against AI-analyzed adverse media coverage",
        "operationId": "adverseMediaCheck",
        "description": "Performs a Google Custom Search for the name, then uses GPT-4o-mini to classify each result as genuine adverse media (with confidence score). Results above 0.4 confidence are returned. Results are cached per-user for 1 hour.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string", "example": "John Smith" },
                  "external_ref": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Screening completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "enum": [true] },
                    "matches": { "type": "array", "items": { "$ref": "#/components/schemas/AdverseMediaMatch" } },
                    "total_matches": { "type": "integer" },
                    "query": { "type": "string" },
                    "request_id": { "type": "string", "format": "uuid" },
                    "timestamp": { "type": "string", "format": "date-time" },
                    "cached": { "type": "boolean" },
                    "warning": { "type": "string" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "503": { "description": "Upstream search service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } },
          "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }
        }
      }
    }
  }
}