{ "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 (free, disposable, role-based, educational, government, ISP, or company) and structured company information for company domains. Company data is grounded by Google Search 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 API key (default tier).", "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": "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_." }, "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 Gemini call instead of using the cached row. Debounced to 60s per domain." }, "include_raw": { "type": "boolean", "default": false, "description": "Include the raw Gemini JSON in meta.raw. Off by default to keep responses small." } } }, "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"], "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 }, "categorization_source": { "type": "string", "enum": ["list", "tld", "fallthrough"] }, "categorization_confidence": { "type": "string", "enum": ["high", "medium", "low"] }, "local_part_role": { "type": "string", "nullable": true }, "request_id": { "type": "string" }, "gemini_error": { "type": "string" }, "served_stale": { "type": "boolean" }, "low_confidence": { "type": "boolean" }, "grounded": { "type": "boolean" }, "grounding_sources": { "type": "array", "items": { "$ref": "#/components/schemas/GroundingSource" } } } } } }, "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" } } } } }, "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." }, "429": { "description": "Rate limit exceeded.", "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/demo/lookup": { "post": { "tags": ["Demo"], "summary": "Anonymous lookup for evaluation", "description": "No auth. IP-rate-limited to 10 requests / minute. Suitable for the public live demo. include_raw is never honored.", "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" } } } }, "429": { "description": "Per-IP rate limit exceeded." } } } }, "/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" } } } } } } } } }, "/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" } } } } } } } } } } }