{"openapi":"3.1.0","info":{"title":"Disban API","version":"1.0.0","description":"Email-domain classification API (Free beta). Free plan: 2,000 checks per UTC month. No payment or automatic billing. Check credits are metered per successful domain, including cache hits. Plan changes retain usage."},"servers":[{"url":"https://disban.io"}],"paths":{"/api/features":{"get":{"operationId":"getAccountFeatures","summary":"Read your effective release flags and plan entitlements","description":"Owner session only. Returns effective booleans and limits, never rollout account lists. Disabled payments cannot be activated through flags.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Effective features and entitlements","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/account/sessions":{"get":{"operationId":"countAccountSessions","summary":"Count your active browser sessions","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Active session count","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/account/{action}":{"post":{"operationId":"manageAccount","summary":"Session and deletion controls","security":[{"sessionCookie":[]}],"description":"Requires a browser session and a fresh action-bound email code requested with intent account. Sign-out-all invalidates every browser session; API keys remain active. Delete-history preserves monthly usage. Delete-account removes the active account, sessions, keys, usage and activity; it does not rewrite independently collected domain intelligence or existing backups.","parameters":[{"in":"path","name":"action","required":true,"schema":{"type":"string","enum":["sign-out-all","delete-history","delete-account"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"challenge_id":{"type":"string"},"code":{"type":"string","pattern":"^(?:[0-9]{6}|[a-f0-9]{32})$","writeOnly":true},"confirmation":{"type":"string","enum":["DELETE"],"description":"Required for both deletion actions."}},"required":["challenge_id","code"]}}}},"responses":{"200":{"description":"Account action completed","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/plans":{"get":{"operationId":"listPlans","summary":"List plans and availability","responses":{"200":{"description":"Plan catalog","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"offer":{"$ref":"#/components/schemas/Offer"}},"required":["plans","offer"]}}}}}}},"/api/auth/otp/request":{"post":{"operationId":"requestEmailCode","summary":"Check a signup email and queue a one-time code","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intent":{"type":"string","enum":["signup","login","account"]},"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":80},"plan_id":{"type":"string","enum":["free"]},"referral_code":{"type":"string","maxLength":24,"description":"Optional referral code; attached only when a new email-verified account is created."},"action":{"type":"string","enum":["sign-out-all","delete-history","delete-account"]}},"required":["intent"]}}}},"description":"Signup requires name/email and passes the backend checker. Login requires email. Account actions require a session and ignore client-supplied email. The response confirms queuing, not delivery. Codes expire 10 minutes after the request and become usable only after the email provider accepts delivery. Resend is limited to once per minute. No account is created until verification.","responses":{"200":{"description":"Generic delivery acknowledgement with challenge_id","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/otp/verify":{"post":{"operationId":"verifyEmailCode","summary":"Consume a one-time code and start a session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intent":{"type":"string","enum":["signup","login"]},"challenge_id":{"type":"string","minLength":64,"maxLength":64},"code":{"type":"string","pattern":"^(?:[0-9]{6}|[a-f0-9]{32})$","writeOnly":true}},"required":["intent","challenge_id","code"]}}}},"responses":{"200":{"description":"Verified account and HttpOnly session cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/logout":{"post":{"operationId":"logout","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Session ended","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/keys":{"get":{"operationId":"listKeys","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Key metadata only; no secrets","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/Key"}}},"required":["keys"]}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createKey","summary":"Issue an API key within the plan limit (Free: one active key)","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}},"responses":{"201":{"description":"Store token now; it is returned only once","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"key":{"$ref":"#/components/schemas/Key"}},"required":["token","key"]}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/keys/{id}":{"delete":{"operationId":"revokeKey","security":[{"sessionCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked; subsequent checks reject the key","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Active key not found","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/referrals":{"get":{"operationId":"getReferrals","summary":"View your referral link, reward counts, policy and bonus expiry dates","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"Private referral summary; no invitee identity details","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/subscription":{"get":{"operationId":"getSubscription","summary":"Inspect plan and current UTC-month usage","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"Current subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"changePlan","summary":"Change plan; shorter retention requires explicit deletion confirmation","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm_deletion":{"type":"boolean","default":false,"description":"Send true only after accepting the retention warning returned with HTTP 409. Older activity is permanently deleted oldest first."},"plan_id":{"type":"string","enum":["free"]}},"required":["plan_id"]}}}},"responses":{"200":{"description":"Plan changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/check":{"post":{"operationId":"checkDomain","parameters":[{"name":"realtime","in":"query","schema":{"type":"boolean"},"description":"false uses stored fresh evidence only; true waits for bounded live routing. Omit to preserve the standard verification flow."}],"security":[{"bearerAuth":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","example":"yopmail.com"}},"required":["input"]}}}},"responses":{"200":{"description":"Classification; consumes one credit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verdict"}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/webhooks/check":{"post":{"operationId":"receiveChecks","security":[{"bearerAuth":[]},{"sessionCookie":[]}],"description":"Inbound push endpoint. Returns ordered results in this response; no outbound callback. Defaults to lookup-only and queues unknown domains for discovery. Same quotas and batch limits as /api/batch.","parameters":[{"name":"realtime","in":"query","schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"input":{"type":"string"}},"required":["input"]},{"type":"object","properties":{"inputs":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}},"required":["inputs"]}]}}}},"responses":{"200":{"description":"Ordered results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Verdict"}}},"required":["results"]}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/batch":{"post":{"operationId":"checkBatch","parameters":[{"name":"realtime","in":"query","schema":{"type":"boolean"},"description":"Applies lookup-only (false) or bounded live checking (true) to every entry."}],"security":[{"bearerAuth":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}},"required":["inputs"]}}}},"responses":{"200":{"description":"Ordered results; failed entries are refunded","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Verdict"},{"type":"object","properties":{"domain":{"type":"string"},"error":{"type":"string"}},"required":["domain","error"]}]}}},"required":["results"]}}}},"400":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate or quota limit; honor Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry"}}},"502":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Request could not be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"dbn_ API key; check, batch, inbound check webhook and read-only subscription"},"sessionCookie":{"type":"apiKey","in":"cookie","name":"disban_session"}},"schemas":{"Account":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","name","email"]}},"required":["user"]},"Plan":{"type":"object","properties":{"id":{"type":"string","enum":["free","launch","growth","scale"]},"selectable":{"type":"boolean","description":"Only Free can be activated. Launch, Growth, and Scale are coming soon."},"name":{"type":"string"},"monthly_checks":{"type":"integer"},"requests_per_second":{"type":"integer"},"planned_monthly_price":{"type":"integer"},"description":{"type":"string"}},"required":["id","name","monthly_checks","requests_per_second","planned_monthly_price"]},"Offer":{"type":"object","properties":{"currency":{"type":"string","const":"USD"},"monthly_price":{"type":"number","const":0},"discount_percent":{"type":"integer","const":0},"payment_required":{"type":"boolean","const":false},"auto_charge":{"type":"boolean","const":false},"terms":{"type":"string"}},"required":["currency","monthly_price","discount_percent","payment_required","auto_charge","terms"]},"Subscription":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/Plan"},"offer":{"$ref":"#/components/schemas/Offer"},"period":{"type":"string","example":"2026-09"},"used":{"type":"integer","description":"Total checks charged this UTC month, including bonus checks."},"monthly_used":{"type":"integer"},"monthly_remaining":{"type":"integer"},"bonus_used":{"type":"integer"},"bonus_remaining":{"type":"integer"},"remaining":{"type":"integer"},"resets_at":{"type":"string","format":"date-time"}},"required":["plan","offer","period","used","remaining","resets_at"]},"Key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"]}},"required":["id","name","prefix","created_at"]},"Verdict":{"type":"object","properties":{"domain":{"type":"string"},"category":{"type":"string","enum":["disposable","free","alias","testing","parked","unknown"]},"reason":{"type":"string"},"status":{"type":"integer","const":200},"email":{"type":["string","null"],"description":"Request-only echo; never persisted in history."},"normalized_email":{"type":["string","null"],"description":"Domain normalized; local-part case preserved. Null for domain-only requests and history."},"domain_authority":{"type":["number","null"]},"domain_age_in_days":{"type":["integer","null"]},"mx":{"type":["boolean","null"],"description":"Fresh explicit non-null MX present. False for Null MX or confirmed absence; null when unverified. False does not exclude implicit SMTP routing."},"mx_records":{"type":["array","null"],"items":{"type":"object","properties":{"hostname":{"type":"string"},"priority":{"type":["integer","null"]}},"required":["hostname","priority"]}},"mx_providers":{"type":["array","null"],"items":{"type":"object","properties":{"slug":{"type":"string"},"type":{"type":"string"},"grade":{"type":["string","null"]}},"required":["slug","type","grade"]}},"spf":{"type":["string","null"]},"dmarc":{"type":["string","null"]},"public_domain":{"type":["boolean","null"]},"relay_domain":{"type":["boolean","null"]},"free_subdomain":{"type":["boolean","null"]},"alias":{"type":["boolean","null"]},"role_account":{"type":["boolean","null"]},"spam":{"type":["boolean","null"]},"did_you_mean":{"type":["string","null"]},"disposable":{"type":["boolean","null"],"description":"Null for unresolved classification; never treat null as clean."},"cached":{"type":"boolean"},"historical_disposable":{"type":"boolean","description":"Records existing list or reviewed seed history, independently of current classification. Can be true for currently confirmed disposable services; it is not a low-confidence flag and is not proof of current operation."},"mail_routing":{"type":"object","properties":{"status":{"type":"string","enum":["routable","invalid","unknown"]},"reason":{"type":"string"},"observed_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"review_required":{"type":"boolean"}},"required":["status","reason"]},"matched_on":{"type":"string"},"latency_ms":{"type":"number"}},"required":["domain","category","reason"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"retry_after":{"type":"integer"}},"required":["error"]}}}}