{
  "openapi": "3.0.0",
  "info": {
    "title": "ValidKit API",
    "version": "1.0.0",
    "description": "Real-time email validation API built for developers. Validates addresses at signup to reduce bounces, catch disposable emails, and understand developer patterns like plus addressing and test accounts.",
    "contact": {
      "email": "support@validkit.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.validkit.com",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/v1/verify": {
      "post": {
        "summary": "Verify a single email address",
        "description": "Performs comprehensive email validation including syntax, DNS, MX records, and disposable email detection.",
        "operationId": "verifyEmail",
        "tags": ["Email Verification"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The email address to verify"
                  },
                  "share_signals": {
                    "type": "boolean",
                    "default": false,
                    "description": "Share validation results with Agent Signal Pool™ to help other AI agents verify emails faster. Starter+ tiers only. Enterprise customers automatically use Private Signal Pools™ isolated to their organization."
                  },
                  "debug": {
                    "type": "boolean",
                    "default": false,
                    "description": "Include detailed validation steps in response"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email verification result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          },
          "504": {
            "$ref": "#/components/responses/UpstreamTimeout"
          }
        }
      }
    },
    "/v2/verify": {
      "post": {
        "summary": "Verify a single email address (v2 — Beta)",
        "description": "**⚠️ Beta**: This endpoint is in beta. The signal vocabulary, decision semantics, and reason codes may change in backwards-incompatible ways before GA. Pin to `result_version` and gate on the `stability` response field (or `X-API-Status` response header) before relying on v2 in production.\n\nPerforms comprehensive email validation and returns typed signal groups, a machine-readable default decision (allow/deny/review), reason codes linked to documentation, and runtime metadata indicating signal availability.",
        "operationId": "verifyEmailV2",
        "x-stability": "beta",
        "tags": ["Email Verification"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "The email address to verify"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "v2 email verification result",
            "headers": {
              "X-Request-ID": {
                "description": "Mirrors `request_id` from the response body for HTTP-level correlation.",
                "schema": { "type": "string" }
              },
              "X-Trace-ID": {
                "description": "Distributed trace identifier for this request.",
                "schema": { "type": "string" }
              },
              "X-Parent-ID": {
                "description": "Mirrors the caller-supplied parent identifier when present (e.g., for distributed tracing across services).",
                "schema": { "type": "string" }
              },
              "X-Processing-Time-MS": {
                "description": "Server-side processing time in milliseconds.",
                "schema": { "type": "string" }
              },
              "X-API-Status": {
                "description": "Contract stability tier — `beta` or `stable`. Mirrors the `stability` field in the response body. HTTP-level consumers (proxies, gateways, log pipelines) can gate on this header without parsing the body.",
                "schema": { "type": "string", "enum": ["beta", "stable"] }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V2VerificationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "description": "Internal server error — non-transient pipeline failure. Transient DNS/network errors do NOT return 500; they return 200 with default_decision: review, runtime.status: degraded, and ttl_hint_seconds: 0 so integrators can retry."
          }
        }
      }
    },
    "/v1/verify/batch": {
      "post": {
        "summary": "Verify multiple email addresses",
        "description": "Verify up to 1000 email addresses in a single request.",
        "operationId": "verifyBatch",
        "tags": ["Email Verification"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["emails"],
                "properties": {
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    },
                    "maxItems": 1000,
                    "description": "Array of email addresses to verify"
                  },
                  "share_signals": {
                    "type": "boolean",
                    "default": false,
                    "description": "Share validation results with Agent Signal Pool™ to help other AI agents verify emails faster. Starter+ tiers only. Enterprise customers automatically use Private Signal Pools™ isolated to their organization."
                  },
                  "debug": {
                    "type": "boolean",
                    "default": false,
                    "description": "Include detailed validation steps in response"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch verification results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/VerificationResult"
                      }
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer"
                        },
                        "valid": {
                          "type": "integer"
                        },
                        "invalid": {
                          "type": "integer"
                        },
                        "unknown": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/bulk/upload": {
      "post": {
        "summary": "Upload CSV for bulk verification",
        "description": "Upload a CSV file containing email addresses for asynchronous bulk verification.",
        "operationId": "uploadBulk",
        "tags": ["Bulk Operations"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "CSV file with email addresses"
                  },
                  "webhook_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL to receive webhook when processing is complete"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Bulk job accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Unique identifier for the bulk job (alias for job_id)"
                    },
                    "job_id": {
                      "type": "string",
                      "description": "Unique identifier for the bulk job"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["queued", "pending", "processing", "completed", "failed"]
                    },
                    "total_emails": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string",
                      "description": "Request tracking identifier"
                    },
                    "trace_id": {
                      "type": "string",
                      "description": "Distributed tracing identifier"
                    },
                    "webhook_url": {
                      "type": "string",
                      "description": "Optional webhook URL for completion notification"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/verify/bulk/agent": {
      "post": {
        "summary": "Agent-optimized bulk verification",
        "description": "Verify up to 10,000+ email addresses with AI-optimized responses. Supports async processing for large batches.",
        "operationId": "verifyBulkAgent",
        "tags": ["Email Verification"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["emails"],
                "properties": {
                  "emails": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    },
                    "description": "Array of email addresses to verify"
                  },
                  "format": {
                    "type": "string",
                    "enum": ["compact", "full"],
                    "default": "compact",
                    "description": "Response format - compact is 80% smaller for AI agents"
                  },
                  "async": {
                    "type": "boolean",
                    "default": false,
                    "description": "Process asynchronously for batches over 1000 emails"
                  },
                  "webhook_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Webhook URL for async results"
                  },
                  "debug": {
                    "type": "boolean",
                    "default": false,
                    "description": "Include detailed validation steps"
                  },
                  "share_signals": {
                    "type": "boolean",
                    "default": false,
                    "description": "Share validation results with Agent Signal Pool™ to help other AI agents verify emails faster. Starter+ tiers only."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "200": {
            "description": "Synchronous batch verification results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentBatchResponse"
                }
              }
            }
          },
          "202": {
            "description": "Asynchronous batch accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "batch_id": {
                      "type": "string",
                      "description": "Unique batch identifier"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["pending", "processing"]
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total emails in batch"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/batch/{batchId}": {
      "get": {
        "summary": "Get batch status",
        "description": "Check the status of an asynchronous batch verification job.",
        "operationId": "getBatchStatus",
        "tags": ["Bulk Operations"],
        "parameters": [
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Batch ID returned from async request"
          }
        ],
        "responses": {
          "200": {
            "description": "Batch status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchStatus"
                }
              }
            }
          },
          "404": {
            "description": "Batch not found"
          }
        }
      },
      "delete": {
        "summary": "Cancel batch job",
        "description": "Cancel an in-progress batch verification job.",
        "operationId": "cancelBatch",
        "tags": ["Bulk Operations"],
        "parameters": [
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Batch ID to cancel"
          }
        ],
        "responses": {
          "200": {
            "description": "Batch cancelled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Batch not found"
          }
        }
      }
    },
    "/v1/batch/{batchId}/results": {
      "get": {
        "summary": "Get batch results",
        "description": "Retrieve the results of a completed batch verification job.",
        "operationId": "getBatchResults",
        "tags": ["Bulk Operations"],
        "parameters": [
          {
            "name": "batchId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Batch ID to get results for"
          }
        ],
        "responses": {
          "200": {
            "description": "Batch results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentBatchResponse"
                }
              }
            }
          },
          "404": {
            "description": "Batch not found"
          },
          "425": {
            "description": "Batch still processing"
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Get usage statistics",
        "description": "Retrieve current usage statistics for your account.",
        "operationId": "getStats",
        "tags": ["Account"],
        "responses": {
          "200": {
            "description": "Usage statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageStats"
                }
              }
            }
          }
        }
      }
    },
    "/v1/accounts/me": {
      "get": {
        "summary": "Get current account",
        "description": "Retrieve information about the current authenticated account.",
        "operationId": "getAccount",
        "tags": ["Account"],
        "responses": {
          "200": {
            "description": "Account information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing API key"
          }
        }
      }
    },
    "/v1/accounts/create": {
      "post": {
        "summary": "Create a new account",
        "description": "Create a new ValidKit account. No authentication required.",
        "operationId": "createAccount",
        "tags": ["Account"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Email address for the new account"
                  },
                  "name": {
                    "type": "string",
                    "description": "Name of the account holder"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "account": {
                      "$ref": "#/components/schemas/Account"
                    },
                    "api_key": {
                      "type": "string",
                      "description": "Generated API key for the new account"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          }
        }
      }
    },
    "/v1/webhooks": {
      "post": {
        "summary": "Configure webhook",
        "description": "Set up a webhook URL to receive verification results.",
        "operationId": "configureWebhook",
        "tags": ["Webhooks"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Webhook endpoint URL"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": ["verification.completed", "bulk.completed", "usage.limit_reached"]
                    },
                    "description": "Events to subscribe to"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook configured successfully"
          }
        }
      }
    },
    "/v1/pool/stats": {
      "get": {
        "summary": "Get Signal Pool statistics",
        "description": "Retrieve current Agent Signal Pool™ statistics including coverage, hit rate, and network size.",
        "operationId": "getPoolStats",
        "tags": ["Signal Pool"],
        "security": [],
        "responses": {
          "200": {
            "description": "Pool statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PoolStats"
                }
              }
            }
          }
        }
      }
    },
    "/v1/pool/contributions": {
      "get": {
        "summary": "Get your contribution history",
        "description": "Retrieve your contribution history and rewards from the Agent Signal Pool™.",
        "operationId": "getMyContributions",
        "tags": ["Signal Pool"],
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["today", "week", "month", "all-time"],
              "default": "week"
            },
            "description": "Time period for contributions"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Page number for pagination"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Results per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Your contribution history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContributionHistory"
                }
              }
            }
          }
        }
      }
    },
    "/v1/pool/leaderboard": {
      "get": {
        "summary": "Get contributor leaderboard",
        "description": "Retrieve the top contributors to the Agent Signal Pool™.",
        "operationId": "getPoolLeaderboard",
        "tags": ["Signal Pool"],
        "security": [],
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["daily", "weekly", "monthly", "all-time"],
              "default": "weekly"
            },
            "description": "Time period for leaderboard"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "description": "Number of top contributors to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Contributor leaderboard",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PoolLeaderboard"
                }
              }
            }
          }
        }
      }
    },
    "/v1/pool/activity": {
      "get": {
        "summary": "Get recent Signal Pool activity",
        "description": "Returns recent validation activity in the Agent Signal Pool™ including cache hits, new domains, and bulk validations. Public endpoint - no authentication required.",
        "operationId": "getPoolActivity",
        "tags": ["Signal Pool"],
        "security": [],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of activity events to return (1-100, default: 50)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Activity retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "activity": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": ["cache_hit", "new_domain", "validation", "bulk"],
                            "description": "Type of activity event"
                          },
                          "message": {
                            "type": "string",
                            "description": "Human-readable activity description"
                          },
                          "timestamp": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "icon": {
                            "type": "string",
                            "description": "Unicode emoji representing the activity type"
                          },
                          "provider": {
                            "type": "string",
                            "description": "Email provider (for new_domain events)"
                          },
                          "source": {
                            "type": "string",
                            "description": "Source of bulk validation (for bulk events)"
                          }
                        },
                        "required": ["type", "message", "timestamp", "icon"]
                      }
                    },
                    "metrics": {
                      "type": "object",
                      "properties": {
                        "events_shown": {
                          "type": "integer",
                          "description": "Number of events returned"
                        },
                        "activity_last_hour": {
                          "type": "integer",
                          "description": "Number of events in the last hour"
                        },
                        "most_common_type": {
                          "type": "string",
                          "description": "Most frequent activity type"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/diagnostic/modules": {
      "get": {
        "summary": "Module diagnostics (TEMPORARY)",
        "description": "TEMPORARY ENDPOINT - Will be removed after deployment issues #160, #161, and #163 are resolved. This endpoint helps diagnose module loading issues in serverless environments. Requires authentication.",
        "operationId": "checkModuleLoading",
        "tags": ["System"],
        "x-temporary": true,
        "x-removal-condition": "After issues #160, #161, and #163 are resolved",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Module loading diagnostic information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "node_version": {
                      "type": "string"
                    },
                    "platform": {
                      "type": "string"
                    },
                    "env": {
                      "type": "object",
                      "description": "Allowed environment variables for security",
                      "properties": {
                        "NODE_ENV": {
                          "type": "string",
                          "description": "Node environment. Valid values: development, production, test. Note: Any unrecognized value will be replaced with 'unknown' to prevent information leakage about the deployment environment.",
                          "enum": ["development", "production", "test", "unknown"]
                        },
                        "VERCEL": {
                          "type": "string",
                          "description": "Whether running on Vercel platform"
                        },
                        "TZ": {
                          "type": "string",
                          "description": "Timezone setting"
                        },
                        "LANG": {
                          "type": "string",
                          "description": "Language/locale setting"
                        }
                      },
                      "additionalProperties": false
                    },
                    "modules": {
                      "type": "object",
                      "description": "Module loading status for each tested module. Failed modules include error message and failed flag, but no stack traces for security.",
                      "additionalProperties": {
                        "oneOf": [
                          {
                            "type": "string",
                            "description": "Success message"
                          },
                          {
                            "type": "object",
                            "properties": {
                              "error": {
                                "type": "string",
                                "description": "Error message without stack trace"
                              },
                              "failed": {
                                "type": "boolean",
                                "description": "Always true for failed modules"
                              }
                            },
                            "required": ["error", "failed"]
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - API key required"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "RateLimitError": {
        "description": "Rate limit exceeded. The limit/retry_after/reset values reflect the limiter applied to the specific endpoint (per-minute for verification, per-hour for account creation). upgrade_url is present only on free-tier authenticated endpoints. Rate-limit headers vary by endpoint (X-RateLimit-* on verify, X-Agent-RateLimit-* on agent); Retry-After is always present.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/RateLimitError"
            }
          }
        }
      },
      "UpstreamError": {
        "description": "Verification service error from the always-on verify service (#3496). Emitted by the Vercel verify proxy on upstream 5xx or mid-flight failure. The request is never re-run — it may have already consumed a validation credit. error.code is UPSTREAM_ERROR; error.retry_after mirrors the Retry-After header.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          },
          "x-verify-origin": {
            "description": "Always 'fly-error' — the proxy attempted the verify service and failed.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UpstreamTimeout": {
        "description": "Verification timed out at the always-on verify service (#3496). The request is never re-run — it may have already consumed a validation credit. error.code is UPSTREAM_TIMEOUT; error.retry_after mirrors the Retry-After header.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          },
          "x-verify-origin": {
            "description": "Always 'fly-error' — the proxy attempted the verify service and failed.",
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "RateLimitError": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "Rate limit exceeded."
              },
              "code": {
                "type": "string",
                "example": "RATE_LIMIT_EXCEEDED"
              },
              "statusCode": {
                "type": "integer",
                "example": 429
              },
              "retry_after": {
                "type": "integer",
                "description": "Seconds until the limit resets.",
                "example": 5
              },
              "limit": {
                "type": "integer",
                "description": "The request limit applicable to this endpoint's window (e.g. per-minute for verification, per-hour for account creation).",
                "example": 60
              },
              "reset": {
                "type": "integer",
                "description": "Unix timestamp (seconds) when the limit resets.",
                "example": 1718400000
              },
              "upgrade_url": {
                "type": "string",
                "description": "Free-tier only: link to upgrade. Omitted for paid tiers.",
                "example": "https://validkit.com/pricing"
              }
            },
            "required": ["message", "code", "statusCode", "retry_after", "limit", "reset"]
          }
        },
        "required": ["success", "error"]
      },
      "V2VerificationResult": {
        "type": "object",
        "required": [
          "email",
          "result_version",
          "stability",
          "request_id",
          "checked_at",
          "default_decision",
          "reasons",
          "signals",
          "runtime",
          "ttl_hint_seconds"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "The email address that was verified (may be syntactically invalid)"
          },
          "result_version": {
            "type": "string",
            "description": "Contract version date (e.g., 2025-12-01). Changes when the response shape changes in a backwards-incompatible way."
          },
          "stability": {
            "type": "string",
            "enum": ["beta", "stable"],
            "description": "Contract stability tier. `beta` means the signal vocabulary, decision semantics, or reason codes may change before GA — pin to `result_version` and watch the changelog. `stable` is the post-GA contract. Mirrored as the `X-API-Status` response header."
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier — also returned in X-Request-ID header"
          },
          "checked_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp of when the email was actually checked. On cache hits, reflects the original check time."
          },
          "default_decision": {
            "type": "string",
            "enum": ["allow", "deny", "review"],
            "description": "ValidKit's recommended decision based on default policy"
          },
          "reasons": {
            "type": "array",
            "description": "Why the decision was made — each code links to documentation",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "description": "Machine-readable reason code"
                },
                "category": {
                  "type": "string",
                  "enum": ["allow", "deny", "review"],
                  "description": "Category of this reason code — maps to the decision direction"
                },
                "docs_slug": {
                  "type": "string",
                  "description": "Documentation slug for this reason"
                }
              },
              "required": ["code", "category", "docs_slug"]
            }
          },
          "signals": {
            "type": "object",
            "description": "Typed signal groups — what was observed during validation",
            "required": ["syntax", "dns", "mx", "disposable", "accept_all", "patterns"],
            "properties": {
              "syntax": {
                "type": "string",
                "enum": ["valid", "invalid"],
                "description": "Email syntax check result"
              },
              "dns": {
                "type": "string",
                "enum": ["resolves", "no_records", "timeout", "error", "not_checked"],
                "description": "DNS resolution result. not_checked means syntax failed before DNS was attempted."
              },
              "mx": {
                "type": "string",
                "enum": ["present", "absent", "timeout", "error", "not_checked"],
                "description": "MX record check result. not_checked means syntax failed before MX was attempted."
              },
              "disposable": {
                "type": "boolean",
                "description": "Whether the email is from a known disposable provider"
              },
              "accept_all": {
                "type": "string",
                "enum": ["yes", "no", "unknown"],
                "description": "Whether the domain accepts all incoming email. unknown means detection is not yet implemented."
              },
              "patterns": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": ["plus_addressing", "developer_test", "system_email", "temporary", "development_env", "ci_cd"]
                },
                "description": "Detected email patterns. Empty array means no patterns matched."
              }
            },
            "additionalProperties": false
          },
          "runtime": {
            "type": "object",
            "description": "Whether all signals were available. If status is degraded, one or more signals could not be resolved.",
            "required": ["status", "unresolved_groups"],
            "properties": {
              "status": {
                "type": "string",
                "enum": ["ok", "degraded"]
              },
              "unresolved_groups": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Signal groups that could not be resolved (timeout or error). not_checked groups are excluded — they were intentionally skipped, not failed."
              }
            }
          },
          "ttl_hint_seconds": {
            "type": "integer",
            "description": "Advisory cache TTL — consumers should not re-validate before this many seconds"
          }
        }
      },
      "VerificationResult": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "valid": {
            "type": "boolean",
            "description": "Overall validity of the email"
          },
          "is_known_valid_fallback": {
            "type": "boolean",
            "description": "True when a major provider domain (gmail.com, outlook.com, etc.) had a transient DNS error and was optimistically accepted via the known-valid-domain safeguard, rather than a confirmed MX resolution."
          },
          "is_dns_fallback": {
            "type": "boolean",
            "description": "True when a transient DNS/resolver error (timeout, resolver unavailable) caused an optimistic accept rather than a confirmed MX resolution. Consumers wanting the full set of non-verified accepts should check is_dns_fallback OR is_known_valid_fallback, not either alone."
          },
          "status": {
            "type": "string",
            "enum": ["valid", "invalid", "unknown"],
            "description": "Verification status"
          },
          "reason": {
            "type": "string",
            "description": "Reason for invalid status"
          },
          "checks": {
            "type": "object",
            "properties": {
              "syntax": {
                "type": "boolean",
                "description": "Email syntax is valid"
              },
              "dns": {
                "type": "boolean",
                "description": "Domain has valid DNS records"
              },
              "mx": {
                "type": "boolean",
                "description": "Domain has valid MX records"
              },
              "disposable": {
                "type": "boolean",
                "description": "Email is from a disposable domain"
              },
              "role": {
                "type": "boolean",
                "description": "Email is a role-based address"
              },
              "free": {
                "type": "boolean",
                "description": "Email is from a free provider"
              }
            }
          },
          "from_pool": {
            "type": "boolean",
            "description": "Result was retrieved from Agent Signal Pool™ (cached by other agents)"
          },
          "pool_confidence": {
            "type": "number",
            "format": "float",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence score based on agent consensus (0-1)"
          },
          "pool_validations": {
            "type": "integer",
            "description": "Number of agents that have validated this email"
          },
          "credits_earned": {
            "type": "integer",
            "description": "Credits earned for contributing this validation to the pool",
            "minimum": 0
          },
          "unique_contribution": {
            "type": "boolean",
            "description": "Whether this was the first validation of this email in the pool"
          },
          "metadata": {
            "type": "object",
            "properties": {
              "domain": {
                "type": "string"
              },
              "provider": {
                "type": "string"
              },
              "did_you_mean": {
                "type": "string",
                "description": "Suggested correction for typos"
              }
            }
          }
        }
      },
      "BulkJobStatus": {
        "type": "object",
        "properties": {
          "job_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "processing", "completed", "failed"]
          },
          "progress": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "processed": {
                "type": "integer"
              },
              "valid": {
                "type": "integer"
              },
              "invalid": {
                "type": "integer"
              }
            }
          },
          "download_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to download results (when completed)"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UsageStats": {
        "type": "object",
        "properties": {
          "current_month": {
            "type": "object",
            "properties": {
              "verifications": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              },
              "remaining": {
                "type": "integer"
              }
            }
          },
          "rate_limits": {
            "type": "object",
            "properties": {
              "per_minute": {
                "type": "integer"
              },
              "per_second": {
                "type": "integer"
              }
            }
          },
          "plan": {
            "type": "string",
            "description": "Current subscription plan"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "code": {
                "type": "string"
              },
              "details": {
                "type": "object"
              }
            }
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique account identifier"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string"
          },
          "plan": {
            "type": "string",
            "description": "Current subscription plan"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AgentBatchResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Request or batch ID"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "i": {
                  "type": "integer",
                  "description": "Index of email in input array"
                },
                "v": {
                  "type": "integer",
                  "description": "Valid flag (1=valid, 0=invalid)"
                },
                "d": {
                  "type": "integer",
                  "description": "Disposable flag (1=disposable, 0=not)"
                },
                "e": {
                  "type": "string",
                  "description": "Error code if invalid (e.g. 'mx', 'syntax')"
                }
              }
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "t": {
                "type": "integer",
                "description": "Total emails processed"
              },
              "v": {
                "type": "integer",
                "description": "Valid emails count"
              },
              "ms": {
                "type": "integer",
                "description": "Processing time in milliseconds"
              },
              "eps": {
                "type": "integer",
                "description": "Emails processed per second"
              }
            }
          }
        }
      },
      "BatchStatus": {
        "type": "object",
        "properties": {
          "batch_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "processing", "completed", "failed", "cancelled"]
          },
          "total": {
            "type": "integer",
            "description": "Total emails in batch"
          },
          "processed": {
            "type": "integer",
            "description": "Emails processed so far"
          },
          "valid": {
            "type": "integer",
            "description": "Valid emails found"
          },
          "invalid": {
            "type": "integer",
            "description": "Invalid emails found"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContributorRank": {
        "type": "object",
        "properties": {
          "rank": {
            "type": "integer",
            "description": "Contributor's rank position"
          },
          "api_key_id": {
            "type": "string",
            "description": "Partially masked API key ID"
          },
          "contributions": {
            "type": "integer",
            "description": "Number of contributions"
          },
          "level": {
            "type": "string",
            "description": "Contributor level name",
            "enum": ["Contributor", "Bronze", "Silver", "Gold", "Diamond"]
          },
          "level_badge": {
            "type": "string",
            "description": "Contributor level badge identifier",
            "enum": ["contributor", "bronze", "silver", "gold", "diamond"]
          }
        }
      },
      "ContributorLevel": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Level name"
          },
          "min_contributions": {
            "type": "integer",
            "description": "Minimum contributions required for this level"
          },
          "count": {
            "type": "integer",
            "description": "Number of contributors at this level"
          }
        }
      },
      "PoolStats": {
        "type": "object",
        "properties": {
          "total_validations": {
            "type": "integer",
            "description": "Total validations in the pool"
          },
          "unique_emails": {
            "type": "integer",
            "description": "Number of unique emails validated"
          },
          "hit_rate": {
            "type": "number",
            "format": "float",
            "description": "Pool hit rate (0-1)"
          },
          "avg_response_time_ms": {
            "type": "number",
            "description": "Average response time in milliseconds"
          },
          "active_contributors": {
            "type": "integer",
            "description": "Number of active contributors"
          },
          "coverage_by_domain": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "Coverage percentage by domain"
          }
        }
      },
      "PoolLeaderboard": {
        "type": "object",
        "properties": {
          "period": {
            "type": "string",
            "description": "Time period for the leaderboard"
          },
          "contributors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "rank": {
                  "type": "integer"
                },
                "contributor_id": {
                  "type": "string",
                  "description": "Anonymized contributor ID"
                },
                "contributions": {
                  "type": "integer",
                  "description": "Number of contributions"
                },
                "unique_contributions": {
                  "type": "integer",
                  "description": "Number of unique email contributions"
                },
                "credits_earned": {
                  "type": "integer",
                  "description": "Total credits earned"
                },
                "badge": {
                  "type": "string",
                  "enum": ["bronze", "silver", "gold", "platinum"],
                  "description": "Contributor badge level"
                }
              }
            }
          }
        }
      },
      "ContributionHistory": {
        "type": "object",
        "properties": {
          "period": {
            "type": "string",
            "description": "Time period for the history"
          },
          "summary": {
            "type": "object",
            "properties": {
              "total_contributions": {
                "type": "integer"
              },
              "unique_contributions": {
                "type": "integer"
              },
              "total_credits": {
                "type": "integer"
              },
              "current_badge": {
                "type": "string",
                "enum": ["bronze", "silver", "gold", "platinum"]
              }
            }
          },
          "contributions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "timestamp": {
                  "type": "string",
                  "format": "date-time"
                },
                "email_hash": {
                  "type": "string",
                  "description": "Hashed email for privacy"
                },
                "credits_earned": {
                  "type": "integer"
                },
                "unique": {
                  "type": "boolean",
                  "description": "Whether this was a unique contribution"
                }
              }
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "page": {
                "type": "integer"
              },
              "limit": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              },
              "has_more": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key for authentication. Get your key at https://validkit.com/dashboard"
      }
    }
  },
  "tags": [
    {
      "name": "Email Verification",
      "description": "Core email verification endpoints"
    },
    {
      "name": "Bulk Operations",
      "description": "Bulk email verification for large lists"
    },
    {
      "name": "Webhooks",
      "description": "Configure webhooks for async notifications"
    },
    {
      "name": "Account",
      "description": "Account management and usage tracking"
    },
    {
      "name": "Signal Pool",
      "description": "Agent Signal Pool™ - Collaborative email validation network"
    }
  ]
}