IntoDNS.ai Web API

openapi: 3.2.0
info:
  title: IntoDNS.AI Web 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: Web
  description: Web security checks and generators
paths:
  /security-headers/analyze:
    get:
      tags:
      - Web
      summary: Analyze live HTTP security headers
      description: Fetch a domain's live HTTP security headers (Strict-Transport-Security, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy), report per-header pass/missing status, and return the recommended baseline config with ready-to-paste fixes. If the header fetch times out, every status is reported as 'unknown' instead of 'missing'.
      operationId: analyzeSecurityHeaders
      parameters:
      - name: domain
        in: query
        required: true
        description: Domain to check
        schema:
          type: string
          example: example.com
      responses:
        '200':
          description: Security headers analysis result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityHeadersAnalyzeResult'
        '400':
          description: Invalid or missing domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /security-headers/generate:
    post:
      tags:
      - Web
      summary: Generate HTTP security headers
      description: Generate HTTP security headers (HSTS, Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, COOP/COEP/CORP) from a named preset or a full config. Returns the header list plus ready-to-paste outputs for Nginx, Apache, Caddy, Cloudflare, _headers files, and raw header lines. Pure compute — no network calls.
      operationId: generateSecurityHeaders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityHeadersGenerateRequest'
      responses:
        '200':
          description: Security headers generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityHeadersGenerateResult'
        '400':
          description: Invalid body — provide a preset or a config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /csp/scan:
    post:
      tags:
      - Web
      summary: Scan a website's Content-Security-Policy
      description: 'Crawl up to 20 same-origin pages (45s total budget), analyze the current Content-Security-Policy (enforce header, Report-Only header, or meta tag), detect weaknesses such as unsafe-inline, wildcard sources, and missing object-src/base-uri/frame-ancestors, inventory every external resource origin per directive, and synthesize a ready-to-deploy starter policy (enforce + Report-Only variants). Expensive endpoint: limited to 3 scans per 10 minutes per IP; results are cached per origin for 10 minutes so repeat scans are instant. A scan typically takes 30-45 seconds.'
      operationId: scanCsp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CspScanRequest'
      responses:
        '200':
          description: CSP scan completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CspScanResult'
        '400':
          description: Invalid body or URL that cannot be scanned (IP literals, localhost, non-https, internal hostnames)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded — 3 scans per 10 minutes per IP; retry after the Retry-After header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Inconclusive — no page could be crawled, so no findings or policy are reported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CspScanInconclusive'
components:
  schemas:
    CspScanInconclusive:
      type: object
      description: Returned with HTTP 502 when zero pages could be crawled — the scan is inconclusive, never a confident negative
      properties:
        error:
          type: string
          example: Could not reach the site
        inconclusive:
          type: boolean
          example: true
        pagesFailed:
          type: integer
    CspScanRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: Site to scan. A bare hostname is treated as https://
          example: https://example.com
        strict:
          type: boolean
          description: Synthesize a stricter policy
          default: false
    SecurityHeadersAnalyzeResult:
      type: object
      properties:
        domain:
          type: string
        scannedAt:
          type: string
          format: date-time
        httpsAvailable:
          type: boolean
        headerFetchTimedOut:
          type: boolean
          description: When true, header absence could not be verified — every status is 'unknown' and a note is set
        note:
          type: string
          description: Present only when the header fetch timed out
        current:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: Content-Security-Policy
              present:
                type: boolean
              value:
                type:
                - string
                - 'null'
              status:
                type: string
                enum:
                - pass
                - missing
                - unknown
        missing:
          type: array
          description: Header names confidently missing (empty when the fetch timed out)
          items:
            type: string
        recommended:
          type: object
          description: The recommended baseline security-headers config
        outputs:
          type: object
          description: Ready-to-paste recommended configuration per server format
        warnings:
          type: array
          items:
            type: string
    CspScanResult:
      type: object
      properties:
        url:
          type: string
          description: Normalized start URL of the crawl
        origin:
          type: string
          example: https://example.com
        pagesCrawled:
          type: integer
          description: Number of same-origin pages successfully crawled (max 20)
        pagesFailed:
          type: integer
        truncated:
          type: boolean
          description: True when more pages were discovered than the crawl budget allowed
        currentCsp:
          type: object
          description: The policy currently deployed, if any
          properties:
            source:
              type:
              - string
              - 'null'
              enum:
              - header
              - report-only
              - meta
              - null
              description: Where the policy was found; null when the site has no CSP
            policy:
              type:
              - string
              - 'null'
        findings:
          type: array
          description: Weaknesses detected in the current policy (or the absence of one)
          items:
            type: object
            properties:
              id:
                type: string
              severity:
                type: string
                enum:
                - critical
                - high
                - medium
                - info
              title:
                type: string
              description:
                type: string
              directive:
                type: string
                example: script-src
        inventory:
          type: array
          description: Observed resource origins grouped by CSP directive ('self' first, externals sorted)
          items:
            type: object
            properties:
              directive:
                type: string
                example: script-src
              origins:
                type: array
                items:
                  type: string
        inlineScripts:
          type: integer
          description: Total inline script blocks across crawled pages
        inlineStyles:
          type: integer
        eventHandlerAttrs:
          type: integer
          description: Total inline event-handler attributes (onclick, onload, ...)
        synthesis:
          type: object
          description: Generated starter policy built from observed resources
          properties:
            policyString:
              type: string
              description: Ready-to-deploy Content-Security-Policy value
            reportOnlyString:
              type: string
              description: Content-Security-Policy-Report-Only value for safe rollout
            notes:
              type: array
              items:
                type: string
    SecurityHeadersGenerateResult:
      type: object
      properties:
        headers:
          type: array
          description: Ordered list of enabled headers
          items:
            type: object
            properties:
              name:
                type: string
                example: Strict-Transport-Security
              value:
                type: string
                example: max-age=31536000; includeSubDomains
        outputs:
          type: object
          description: Ready-to-paste configuration per server format
          properties:
            nginx:
              type: string
            apache:
              type: string
            caddy:
              type: string
            cloudflare:
              type: string
            headers:
              type: string
              description: Netlify/Vercel-style _headers file
            raw:
              type: string
        warnings:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: INVALID_DOMAIN
            message:
              type: string
              example: The provided domain is not valid
            details:
              type: string
    SecurityHeadersGenerateRequest:
      type: object
      description: Provide either a named preset or a full config. If both are present, config wins and preset is ignored.
      properties:
        preset:
          type: string
          enum:
          - recommended
          - strict
          - report-only
          description: Named baseline configuration
          example: recommended
        config:
          type: object
          description: Full security-headers config with hsts, csp, frameOptions, contentTypeOptions, referrerPolicy, permissionsPolicy, coop, coep, and corp fields
  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.