IntoDNS.ai AI API

openapi: 3.2.0
info:
  title: IntoDNS. AI API
  description: Public DNS security and email deliverability analysis API. Analyze SPF, DKIM, DMARC, DNSSEC, MTA-STS, BIMI, SMTP STARTTLS, FCrDNS, blacklists, and more with deterministic results and optional AI explanations.
  version: 2.0.0
  contact:
    name: IntoDNS.AI Support
    url: https://intodns.ai
    email: support@cobytes.com
  license:
    name: Proprietary
    url: https://intodns.ai/terms
servers:
- url: https://intodns.ai/api
  description: Production server
security: []
tags:
- name: AI
  description: AI-assisted explanations and fixes
paths:
  /ai/explain:
    post:
      tags:
      - AI
      summary: AI explanation
      description: Get an AI-assisted explanation for DNS or email security issues. Requires a signed-in free IntoDNS.ai account using the existing Auth.js session cookie. Shares a free per-account daily allowance with /ai/fix, plus burst protection and a service-wide daily budget. Public diagnostic scans do not require this session.
      operationId: aiExplain
      security:
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIExplainRequest'
      responses:
        '200':
          description: AI explanation generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIExplainResponse'
        '401':
          description: Missing, invalid, or expired session. Sign in at https://intodns.ai/login through the normal browser flow; anonymous agents should use public diagnostic endpoints instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIAuthenticationError'
        '429':
          description: AI account allowance, burst protection, or service-wide daily budget reached. Respect Retry-After before retrying.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
  /ai/fix:
    post:
      tags:
      - AI
      summary: AI fix suggestion
      description: Get AI-assisted fix recommendations with configuration examples. Requires a signed-in free IntoDNS.ai account using the existing Auth.js session cookie. Shares a free per-account daily allowance with /ai/explain, plus burst protection and a service-wide daily budget. Public diagnostic scans and record generators do not require this session.
      operationId: aiFix
      security:
      - SessionCookie: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AIFixRequest'
      responses:
        '200':
          description: Fix suggestion generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIFixResponse'
        '401':
          description: Missing, invalid, or expired session. Sign in at https://intodns.ai/login through the normal browser flow; anonymous agents should use public diagnostic endpoints instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AIAuthenticationError'
        '429':
          description: AI account allowance, burst protection, or service-wide daily budget reached. Respect Retry-After before retrying.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
components:
  schemas:
    AIAuthenticationError:
      type: object
      required:
      - error
      - requiresAccount
      properties:
        error:
          type: string
          enum:
          - Unauthorized
        requiresAccount:
          type: boolean
          enum:
          - true
    AIFixRequest:
      type: object
      required:
      - issue
      - domain
      properties:
        issue:
          type: string
          example: no_dmarc
        domain:
          type: string
          example: example.com
        context:
          type: object
          example: {}
    AIExplainResponse:
      type: object
      required:
      - data
      - cached
      - source
      - timestamp
      properties:
        data:
          type: object
          required:
          - explanation
          - importance
          - impact
          - steps
          properties:
            explanation:
              type: string
            importance:
              type: string
              enum:
              - low
              - medium
              - high
              - critical
            impact:
              type: string
            steps:
              type: array
              items:
                type: string
            learnMore:
              type: string
              description: Optional reference for further reading.
        cached:
          type: boolean
          description: True for pre-built or fallback helper output. Preserved on API cache hits; this is not an API cache-hit indicator.
        source:
          type: string
          enum:
          - pre-built
          - claude-api
        timestamp:
          type: integer
          description: Unix time in milliseconds when the helper response was generated. Preserved when serving a cached response.
    AIFixResponse:
      type: object
      required:
      - data
      - cached
      - source
      - timestamp
      properties:
        data:
          type: object
          required:
          - explanation
          - solution
          - config
          - instructions
          - warnings
          properties:
            explanation:
              type: string
            solution:
              type: string
            config:
              type: string
            instructions:
              type: array
              items:
                type: string
            warnings:
              type: array
              items:
                type: string
        cached:
          type: boolean
          description: True for pre-built or fallback helper output. Preserved on API cache hits; this is not an API cache-hit indicator.
        source:
          type: string
          enum:
          - pre-built
          - claude-api
        timestamp:
          type: integer
          description: Unix time in milliseconds when the helper response was generated. Preserved when serving a cached response.
    AIExplainRequest:
      type: object
      required:
      - issue
      - domain
      properties:
        issue:
          type: string
          example: spf_too_many_lookups
        domain:
          type: string
          example: example.com
        context:
          type: object
          example:
            lookupCount: 12
  securitySchemes:
    SessionCookie:
      type: apiKey
      in: cookie
      name: __Secure-authjs.session-token
      description: Auth.js JWT session established by signing in at https://intodns.ai/login. On HTTPS the cookie is HttpOnly, Secure, SameSite=Lax, Path=/. Local HTTP development uses authjs.session-token without Secure. Auth.js manages cookies and numbered chunks when needed. This is browser session authentication, not an API key or bearer token; do not construct tokens or share session cookies with AI assistants. OpenAPI 3 represents cookie authentication with type apiKey.
x-access:
  authentication: None for public diagnostics; POST /ai/explain and POST /ai/fix require a signed-in free account using an Auth.js session cookie.
  publicEndpoints: Public DNS, email, blacklist, quick-scan, Everything Report, report snapshot, and record generator endpoints are free and available without signup or API keys for normal diagnostic use. Generous abuse protection may return HTTP 429 with Retry-After for bursts and write-style snapshot creation.
  canonicalApiOrigin: https://intodns.ai/api
  invalidApiOrigins:
  - https://api.intodns.io
  - https://intodns.io/api-docs/v1
  invalidApiExamples:
  - https://api.intodns.io/v1/domain/{domain}
  - https://api.intodns.io/v1/domain/example.com
  llmDiscovery: 'LLM discovery files are static and cacheable: /llms.txt, /llms-full.txt, /llms.json, /llm/api.md.'
  protection: Costly write-style or AI/raw-message endpoints may return HTTP 429 with Retry-After if abuse protection triggers.