{
  "openapi": "3.1.0",
  "info": {
    "title": "pingutil Domain Intelligence API",
    "version": "1.0.0",
    "summary": "Classify any email or domain and enrich company info in a single REST call.",
    "description": "pingutil takes any email address or domain and returns a category (company, free, disposable, isp, educational, government or unknown), heuristic email signals, a spam verdict, and structured company information for company domains. Company profiles are generated by an AI model (gpt-oss-20b on Cloudflare Workers AI by default, grounded with the company's homepage; optionally Gemini with Google Search grounding), validated against a schema and cached in Cloudflare D1.\n\n**Auth**: Bearer API key. Get one free at https://pingutil.com/dashboard.\n\n**Rate limit**: 60 requests/minute per account, shared across all of the account's API keys (at most 3 active keys, 5 new keys per day). Exceeding it returns 429 `rate_limited` with `retry_after_seconds`.\n\n**Daily budgets** (per account, reset 00:00 UTC): 2,000 lookups (cache hits included); 50 fresh company profiles (LLM enrichment, including refresh=true; cached results don't count); 300 email verifications (/v1/verify, /v1/verify/batch and dashboard CSV uploads combined). Over the lookup or verification budget: 429 `quota_exceeded`. Over the profile budget the lookup still returns 200 with `meta.enrichment_error = \"daily_enrichment_limit\"` (and a stale cached profile if one exists). Domains that don't resolve in DNS never get a profile (`meta.enrichment_error = \"domain_unresolvable\"`).\n\n**Other limits**: request bodies over 32 KB return 413 `payload_too_large`. If usage limits are temporarily unavailable the API returns 503 `quota_unavailable`.",
    "contact": {
      "name": "pingutil",
      "url": "https://pingutil.com",
      "email": "hello@pingutil.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://pingutil.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Lookup",
      "description": "Primary lookup endpoints (API key required)."
    },
    {
      "name": "Verification",
      "description": "Mailbox-level email verification."
    },
    {
      "name": "Demo",
      "description": "Anonymous, IP-rate-limited lookup for evaluation."
    },
    {
      "name": "Cache",
      "description": "Cache-only domain access."
    },
    {
      "name": "Keys",
      "description": "API key management (signed-in user JWT)."
    },
    {
      "name": "Auth",
      "description": "OIDC callback used by the dashboard."
    },
    {
      "name": "Health",
      "description": "Liveness probe."
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Issued in the dashboard. Format: pk_live_<random>."
      },
      "UserJwt": {
        "type": "http",
        "scheme": "bearer",
        "description": "MojoAuth-issued OIDC id_token. Used for /v1/keys/* only."
      }
    },
    "schemas": {
      "LookupRequest": {
        "type": "object",
        "required": [
          "input"
        ],
        "properties": {
          "input": {
            "type": "string",
            "minLength": 1,
            "maxLength": 320,
            "description": "Email or domain. Examples: 'jane@stripe.com', 'stripe.com'.",
            "example": "jane@stripe.com"
          },
          "refresh": {
            "type": "boolean",
            "default": false,
            "description": "Force a fresh enrichment-provider call instead of using the cached row. Debounced to 60s per domain. Counts against the account's 50 fresh profiles per day."
          },
          "include_raw": {
            "type": "boolean",
            "default": false,
            "description": "Include the raw provider JSON in meta.raw. Off by default to keep responses small."
          },
          "skip_enrichment": {
            "type": "boolean",
            "default": false,
            "description": "Skip the company profile (no AI call). Returns category, email_signals and verdict in milliseconds."
          },
          "check_reputation": {
            "type": "boolean",
            "description": "Run the third-party reputation check when configured on the server. Defaults to the opposite of skip_enrichment."
          },
          "check_dns": {
            "type": "boolean",
            "default": false,
            "description": "Resolve domain_signals via DNS-over-HTTPS (cached 7 days). Informational; does not change verdict."
          }
        }
      },
      "Headquarters": {
        "type": "object",
        "nullable": true,
        "properties": {
          "city": {
            "type": "string",
            "nullable": true
          },
          "region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "GroundingSource": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "snippet": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "Company": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "legal_name": {
            "type": "string",
            "nullable": true
          },
          "tagline": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "industry": {
            "type": "string",
            "nullable": true
          },
          "sub_industry": {
            "type": "string",
            "nullable": true
          },
          "tech_categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "founded_year": {
            "type": "integer",
            "nullable": true
          },
          "headquarters": {
            "$ref": "#/components/schemas/Headquarters"
          },
          "employee_size_estimate": {
            "type": "string",
            "nullable": true,
            "enum": [
              "1-10",
              "11-50",
              "51-200",
              "201-500",
              "501-1000",
              "1001-5000",
              "5001-10000",
              "10000+"
            ]
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "linkedin_url": {
            "type": "string",
            "nullable": true
          },
          "twitter_handle": {
            "type": "string",
            "nullable": true
          },
          "crunchbase_url": {
            "type": "string",
            "nullable": true
          },
          "github_org": {
            "type": "string",
            "nullable": true
          },
          "parent_company": {
            "type": "string",
            "nullable": true
          },
          "funding_stage": {
            "type": "string",
            "nullable": true,
            "enum": [
              "bootstrapped",
              "seed",
              "series_a",
              "series_b",
              "series_c",
              "series_d_plus",
              "public",
              "acquired",
              "unknown"
            ]
          },
          "total_funding_usd": {
            "type": "integer",
            "nullable": true
          },
          "notable_customers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "is_public": {
            "type": "boolean",
            "nullable": true
          },
          "ticker": {
            "type": "string",
            "nullable": true
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "nullable": true
          }
        }
      },
      "LookupResponse": {
        "type": "object",
        "required": [
          "domain",
          "category",
          "is_email",
          "cached",
          "fetched_at",
          "company",
          "meta",
          "verdict"
        ],
        "properties": {
          "domain": {
            "type": "string",
            "description": "Registrable (eTLD+1) form, lowercased, punycoded."
          },
          "domain_unicode": {
            "type": "string",
            "description": "IDN-decoded display form."
          },
          "category": {
            "type": "string",
            "enum": [
              "free",
              "disposable",
              "educational",
              "government",
              "isp",
              "company",
              "unknown"
            ]
          },
          "subcategory": {
            "type": "string",
            "nullable": true
          },
          "is_email": {
            "type": "boolean"
          },
          "input_normalized": {
            "type": "string"
          },
          "cached": {
            "type": "boolean"
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_refreshed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "company": {
            "$ref": "#/components/schemas/Company",
            "nullable": true
          },
          "meta": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string",
                "nullable": true,
                "description": "What produced this row: the AI model id (e.g. @cf/openai/gpt-oss-20b, gemini-2.5-flash) or 'ipqs' for spam verdicts"
              },
              "categorization_source": {
                "type": "string",
                "enum": [
                  "list",
                  "tld",
                  "fallthrough",
                  "ipqs"
                ]
              },
              "categorization_confidence": {
                "type": "string",
                "enum": [
                  "high",
                  "medium",
                  "low"
                ]
              },
              "local_part_role": {
                "type": "string",
                "nullable": true
              },
              "request_id": {
                "type": "string"
              },
              "enrichment_error": {
                "type": "string",
                "description": "Set when no fresh company profile was built: a provider error, \"domain_unresolvable\" (the domain doesn't resolve in DNS) or \"daily_enrichment_limit\" (the account's 50 fresh profiles for the day are used up)."
              },
              "served_stale": {
                "type": "boolean"
              },
              "low_confidence": {
                "type": "boolean"
              },
              "grounded": {
                "type": "boolean"
              },
              "grounding_sources": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/GroundingSource"
                }
              }
            }
          },
          "email_signals": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EmailSignals"
              }
            ],
            "nullable": true
          },
          "domain_signals": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DomainSignals"
              }
            ],
            "nullable": true
          },
          "verdict": {
            "$ref": "#/components/schemas/Verdict"
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "retry_after_seconds": {
            "type": "integer"
          }
        }
      },
      "ApiKeySummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "tier": {
            "type": "string",
            "enum": [
              "standard",
              "admin"
            ]
          },
          "rate_limit_per_minute": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "revoked": {
            "type": "boolean"
          }
        }
      },
      "EmailSignals": {
        "type": "object",
        "description": "Heuristics on the local part. Null for bare-domain input.",
        "properties": {
          "is_randomized": {
            "type": "boolean",
            "description": "Machine-generated local part. Sets verdict.is_spam."
          },
          "randomness_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "is_role_based": {
            "type": "boolean"
          },
          "is_system_generated": {
            "type": "boolean"
          },
          "is_sales_outreach": {
            "type": "boolean"
          },
          "domain_looks_random": {
            "type": "boolean"
          }
        }
      },
      "DomainSignals": {
        "type": "object",
        "description": "Present only when check_dns is true.",
        "properties": {
          "domain_exists": {
            "type": "boolean"
          },
          "can_receive_email": {
            "type": "boolean"
          },
          "has_website": {
            "type": "boolean"
          }
        }
      },
      "Verdict": {
        "type": "object",
        "required": [
          "is_spam",
          "low_trust",
          "reason"
        ],
        "properties": {
          "is_spam": {
            "type": "boolean",
            "description": "Block on this: disposable or reputation-flagged domain, or randomized local part."
          },
          "low_trust": {
            "type": "boolean",
            "description": "Role, system or sales address. Review rather than block."
          },
          "reason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "disposable_domain",
              "randomized_local_part",
              "role_based",
              "system_generated",
              "sales_outreach",
              null
            ]
          }
        }
      },
      "EmailVerification": {
        "type": "object",
        "required": [
          "email",
          "input",
          "status",
          "reason",
          "score",
          "did_you_mean",
          "checks",
          "mx_host",
          "smtp",
          "cached",
          "checked_at"
        ],
        "properties": {
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "Normalized address; null when it could not be parsed."
          },
          "input": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "valid",
              "invalid",
              "risky",
              "unknown"
            ],
            "description": "valid: mailbox confirmed. invalid: will not deliver. risky: may exist but unsafe (catch-all, role, full, machine-generated). unknown: server gave no clear answer."
          },
          "reason": {
            "type": "string",
            "enum": [
              "mailbox_exists",
              "invalid_syntax",
              "disposable_domain",
              "no_domain",
              "no_mx",
              "null_mx",
              "mailbox_not_found",
              "mailbox_disabled",
              "accept_all",
              "role_based",
              "randomized_local_part",
              "mailbox_full",
              "greylisted",
              "blocked",
              "rate_limited",
              "timeout",
              "connection_failed",
              "smtp_error",
              "dns_error",
              "smtp_unavailable"
            ]
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "did_you_mean": {
            "type": [
              "string",
              "null"
            ],
            "description": "Suggested address when the domain looks like a typo of a major provider."
          },
          "checks": {
            "type": "object",
            "properties": {
              "syntax": {
                "type": "boolean"
              },
              "disposable": {
                "type": "boolean"
              },
              "free_provider": {
                "type": "boolean"
              },
              "role_based": {
                "type": "boolean"
              },
              "randomized": {
                "type": "boolean"
              },
              "domain_exists": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "has_mx": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "mailbox": {
                "type": "string",
                "enum": [
                  "exists",
                  "not_found",
                  "disabled",
                  "full",
                  "accept_all",
                  "unknown",
                  "not_checked"
                ]
              },
              "catch_all": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            }
          },
          "mx_host": {
            "type": [
              "string",
              "null"
            ]
          },
          "smtp": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "integer"
              },
              "enhanced": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          },
          "cached": {
            "type": "boolean"
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "paths": {
    "/v1/lookup": {
      "post": {
        "tags": [
          "Lookup"
        ],
        "summary": "Look up an email or domain (authenticated)",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LookupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lookup result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "413": {
            "description": "Request body over 32 KB (`payload_too_large`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited` (over 60 requests/minute per account; wait retry_after_seconds) or `quota_exceeded` (2,000 lookups per account per day used up; resets 00:00 UTC).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "`quota_unavailable`: usage limits temporarily unavailable. Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Lookup"
        ],
        "summary": "Look up an email or domain (query-string variant)",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "input",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refresh",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/verify": {
      "post": {
        "tags": [
          "Verification"
        ],
        "summary": "Verify one email address",
        "description": "Syntax, disposable-domain, DNS/MX, then an SMTP RCPT TO handshake with the domain's mail server (no message is sent) plus a catch-all probe. Cached 30 days (unknown: 1 hour) under a SHA-256 hash of the address.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "maxLength": 320
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailVerification"
                }
              }
            }
          },
          "400": {
            "description": "Invalid body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "Request body over 32 KB (`payload_too_large`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited` (over 60 requests/minute per account) or `quota_exceeded` (300 addresses per account per day used up, API and dashboard CSV combined; resets 00:00 UTC).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "`quota_unavailable`: usage limits temporarily unavailable. Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      },
      "get": {
        "tags": [
          "Verification"
        ],
        "summary": "Verify one email address (query string)",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailVerification"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/verify/batch": {
      "post": {
        "tags": [
          "Verification"
        ],
        "summary": "Verify up to 50 addresses",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "emails"
                ],
                "properties": {
                  "emails": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results in input order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EmailVerification"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "Request body over 32 KB (`payload_too_large`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited` (over 60 requests/minute per account) or `quota_exceeded` (the batch would exceed 300 addresses per account per day, API and dashboard CSV combined; resets 00:00 UTC).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "503": {
            "description": "`quota_unavailable`: usage limits temporarily unavailable. Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/demo/session": {
      "post": {
        "tags": [
          "Demo"
        ],
        "summary": "Exchange a Turnstile token for a demo session",
        "description": "No API key. Called by the pingutil.com website after the visitor solves a Cloudflare Turnstile challenge. Verifies the token with Cloudflare and returns a session token valid for 30 minutes, bound to the caller's IP (IPv6 per /64), to send as the x-demo-session header on /v1/demo/lookup and /v1/demo/verify. Counts toward the demo's 6 requests/minute per IP. When Turnstile is not configured on the server, returns token: null, expires_in: null, required: false.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "turnstile_token"
                ],
                "properties": {
                  "turnstile_token": {
                    "type": "string",
                    "description": "Token produced by the Turnstile widget."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Demo session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "token",
                    "expires_in",
                    "required"
                  ],
                  "properties": {
                    "token": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Session token for the x-demo-session header; null when Turnstile is not required."
                    },
                    "expires_in": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Seconds until the session expires (1800); null when Turnstile is not required."
                    },
                    "required": {
                      "type": "boolean",
                      "description": "Whether the demo endpoints enforce x-demo-session."
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "`turnstile_failed`: Cloudflare rejected the Turnstile token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Per-IP rate limit exceeded (`rate_limited`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/demo/lookup": {
      "post": {
        "tags": [
          "Demo"
        ],
        "summary": "Anonymous lookup for evaluation",
        "description": "No API key. Rate-limited to 6 requests/minute per IP (IPv6 counted per /64), shared with /v1/demo/verify. Suitable for the public live demo. include_raw and refresh are never honored, and the demo never calls IPQS. New company profiles are capped per day across all anonymous visitors (50); past the cap the demo answers from cache. Browser calls are only accepted from pingutil.com. Protected by Cloudflare Turnstile: requires the x-demo-session header from POST /v1/demo/session, which only the pingutil.com website can obtain. Scripts and servers should use /v1/lookup with an API key.",
        "parameters": [
          {
            "name": "x-demo-session",
            "in": "header",
            "required": true,
            "description": "Demo session token from POST /v1/demo/session (30 minutes, bound to the caller's IP; IPv6 per /64). Only the pingutil.com website can obtain one, because it requires solving a Cloudflare Turnstile challenge in the browser.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "properties": {
                  "input": {
                    "type": "string"
                  },
                  "refresh": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lookup result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              }
            }
          },
          "401": {
            "description": "`turnstile_required`: missing, expired or wrong-IP `x-demo-session`. The demo is for the pingutil.com website only; from code, use /v1/lookup or /v1/verify with an API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "`forbidden`: called from a browser page on another origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "Request body over 32 KB (`payload_too_large`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Per-IP rate limit exceeded (`rate_limited`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/demo/verify": {
      "post": {
        "tags": [
          "Demo"
        ],
        "summary": "Anonymous single-address verification",
        "description": "No API key. Rate-limited to 6 requests/minute per IP (IPv6 counted per /64), shared with /v1/demo/lookup, and additionally 3 verifications/minute per IP. Mailbox checks are capped per day across all visitors (150); past the cap the result is DNS-only with reason smtp_unavailable. Browser calls are only accepted from pingutil.com. Protected by Cloudflare Turnstile: requires the x-demo-session header from POST /v1/demo/session, which only the pingutil.com website can obtain. Scripts and servers should use /v1/verify with an API key.",
        "parameters": [
          {
            "name": "x-demo-session",
            "in": "header",
            "required": true,
            "description": "Demo session token from POST /v1/demo/session (30 minutes, bound to the caller's IP; IPv6 per /64). Only the pingutil.com website can obtain one, because it requires solving a Cloudflare Turnstile challenge in the browser.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "maxLength": 320
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailVerification"
                }
              }
            }
          },
          "401": {
            "description": "`turnstile_required`: missing, expired or wrong-IP `x-demo-session`. The demo is for the pingutil.com website only; from code, use /v1/lookup or /v1/verify with an API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "403": {
            "description": "`forbidden`: called from a browser page on another origin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "413": {
            "description": "Request body over 32 KB (`payload_too_large`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "429": {
            "description": "Per-IP rate limit exceeded (`rate_limited`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/domains/{domain}": {
      "get": {
        "tags": [
          "Cache"
        ],
        "summary": "Read a domain from cache only",
        "description": "Returns 404 if the domain has never been looked up. Useful for backfill/audit pipelines.",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cached lookup result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LookupResponse"
                }
              }
            }
          },
          "404": {
            "description": "Domain not in cache."
          }
        }
      }
    },
    "/v1/keys": {
      "get": {
        "tags": [
          "Keys"
        ],
        "summary": "List the signed-in user's API keys",
        "security": [
          {
            "UserJwt": []
          }
        ],
        "responses": {
          "200": {
            "description": "Key list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKeySummary"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Keys"
        ],
        "summary": "Create a new API key",
        "security": [
          {
            "UserJwt": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Optional human-readable label."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Newly minted key. The full secret is returned exactly once.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "key": {
                      "type": "string",
                      "description": "Full secret. Store immediately."
                    },
                    "prefix": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string",
                      "nullable": true
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`quota_exceeded`: the account already has 3 active keys, or has created 5 keys today.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/keys/{id}": {
      "delete": {
        "tags": [
          "Keys"
        ],
        "summary": "Revoke an API key",
        "security": [
          {
            "UserJwt": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Revoked."
          }
        }
      }
    },
    "/v1/auth/callback": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "OIDC callback — exchange authorization code for id_token",
        "description": "Used by the dashboard after MojoAuth redirects back with ?code=…&state=…. Not intended for direct client use.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code",
                  "redirect_uri"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "redirect_uri": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Exchanged token.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id_token": {
                      "type": "string"
                    },
                    "expires_in": {
                      "type": "integer",
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Liveness probe",
        "responses": {
          "200": {
            "description": "Healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "version": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
