{
  "openapi": "3.1.0",
  "info": {
    "title": "Veritas verification API",
    "version": "1.0.0",
    "description": "Email verification, identity/financial document checksums and phone parsing. Usage-based pricing with a free tier; every endpoint is metered and rate limited per plan.",
    "contact": {
      "email": "suporte@rohnelt.dev"
    }
  },
  "servers": [
    {
      "url": "https://autorev.rohnelt.dev"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your API key, issued at POST /v1/signup"
      }
    }
  },
  "paths": {
    "/v1/signup": {
      "post": {
        "summary": "Create an account and receive an API key",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "name": {
                    "type": "string"
                  },
                  "company": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "plan": {
                    "type": "string",
                    "enum": [
                      "free",
                      "starter",
                      "growth",
                      "scale"
                    ]
                  },
                  "referral_code": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "account_id": {
                      "type": "string"
                    },
                    "api_key": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unusable email",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Already exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/email/verify": {
      "get": {
        "summary": "Verify a single email address",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "Address to verify",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deep",
            "in": "query",
            "required": false,
            "description": "Add SPF/DMARC lookups (2 units)",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "dns",
            "in": "query",
            "required": false,
            "description": "Perform DNS checks (default true)",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "deliverable",
                        "risky",
                        "undeliverable",
                        "unknown"
                      ]
                    },
                    "sub_status": {
                      "type": "string"
                    },
                    "score": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "normalized": {
                      "type": "string"
                    },
                    "has_mx": {
                      "type": "boolean"
                    },
                    "mx_hosts": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "is_disposable": {
                      "type": "boolean"
                    },
                    "is_role": {
                      "type": "boolean"
                    },
                    "is_free_provider": {
                      "type": "boolean"
                    },
                    "gibberish_score": {
                      "type": "number"
                    },
                    "did_you_mean": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Bad key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/email/batch": {
      "post": {
        "summary": "Verify many addresses in one call",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "deep": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "summary": {
                      "type": "object"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "email": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "deliverable",
                              "risky",
                              "undeliverable",
                              "unknown"
                            ]
                          },
                          "sub_status": {
                            "type": "string"
                          },
                          "score": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 100
                          },
                          "normalized": {
                            "type": "string"
                          },
                          "has_mx": {
                            "type": "boolean"
                          },
                          "mx_hosts": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "is_disposable": {
                            "type": "boolean"
                          },
                          "is_role": {
                            "type": "boolean"
                          },
                          "is_free_provider": {
                            "type": "boolean"
                          },
                          "gibberish_score": {
                            "type": "number"
                          },
                          "did_you_mean": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "reasons": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Batch too large",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/identity/validate": {
      "get": {
        "summary": "Validate a document by type",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "cpf",
                "cnpj",
                "iban",
                "vat",
                "card",
                "isbn",
                "ean13",
                "ein"
              ]
            }
          },
          {
            "name": "value",
            "in": "query",
            "required": true,
            "description": "Document value",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result"
          },
          "401": {
            "description": "Bad key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/identity/autodetect": {
      "get": {
        "summary": "Detect and validate an unknown document",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "value",
            "in": "query",
            "required": true,
            "description": "Document value",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result"
          }
        }
      }
    },
    "/v1/phone/validate": {
      "get": {
        "summary": "Parse and validate a phone number",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "phone",
            "in": "query",
            "required": true,
            "description": "Number in any format",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Default calling code, e.g. 55",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Parsed number"
          }
        }
      }
    },
    "/v1/account": {
      "get": {
        "summary": "Plan, usage and projected invoice",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account state"
          }
        }
      }
    },
    "/v1/account/plan": {
      "post": {
        "summary": "Self-serve plan change",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Updated plan"
          }
        }
      }
    },
    "/v1/account/invoices": {
      "get": {
        "summary": "Invoice history",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Invoices"
          }
        }
      }
    },
    "/v1/plans": {
      "get": {
        "summary": "Public plan catalogue",
        "responses": {
          "200": {
            "description": "Plans"
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Full self-diagnosis",
        "responses": {
          "200": {
            "description": "Healthy or degraded"
          },
          "503": {
            "description": "Failing"
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Liveness probe",
        "responses": {
          "200": {
            "description": "Alive"
          }
        }
      }
    }
  }
}