openapi: 3.2.0
info:
  title: DomScan Meta API
  description: DomScan is a domain intelligence API providing domain analysis tools.
  version: 2.15.0
  contact:
    name: DomScan Support
    url: https://domscan.net
    email: support@domscan.net
  termsOfService: https://domscan.net/legal/terms
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://domscan.net
  description: Production server
security:
- apiKey: []
tags:
- name: Meta
  description: API information and system endpoints
paths:
  /v1/openapi.json:
    get:
      tags:
      - Meta
      summary: Download the OpenAPI 3.0 specification
      description: Returns the machine-readable OpenAPI 3.0 document for the DomScan API.
      operationId: getOpenApiSpec
      security: []
      responses:
        '200':
          description: OpenAPI 3.0 specification
          content:
            application/json:
              schema:
                type: object
        '429':
          $ref: '#/components/responses/RateLimited'
      x-domscan-credits:
        model: per_request
        default: 0
  /v1/swagger.json:
    get:
      tags:
      - Meta
      summary: Download the Swagger 2.0 specification
      description: Returns the Swagger 2.0 version of the API specification for tools that prefer Swagger over OpenAPI 3.
      operationId: getSwaggerSpec
      security: []
      responses:
        '200':
          description: Swagger 2.0 specification
          content:
            application/json:
              schema:
                type: object
  /v1/postman.json:
    get:
      tags:
      - Meta
      summary: Download the Postman collection
      description: Returns the Postman collection for importing the DomScan API into Postman or compatible API clients.
      operationId: getPostmanCollection
      security: []
      responses:
        '200':
          description: Postman collection
          content:
            application/json:
              schema:
                type: object
  /v1/rapidapi.json:
    get:
      tags:
      - Meta
      summary: Download the RapidAPI marketplace specification
      description: Returns the filtered OpenAPI 3.0 contract for importing supported stateless DomScan operations into RapidAPI Studio.
      operationId: getRapidApiSpec
      security: []
      responses:
        '200':
          description: RapidAPI marketplace OpenAPI specification
          content:
            application/json:
              schema:
                type: object
  /v1/pricing:
    get:
      tags:
      - Meta
      summary: Get API pricing info
      description: Get credit costs per endpoint and information about the pricing model. This endpoint is free and does not require authentication.
      operationId: getPricingInfo
      security: []
      responses:
        '200':
          description: API pricing information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiPricingResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-domscan-credits:
        model: per_request
        default: 0
components:
  responses:
    RateLimited:
      description: Rate limit exceeded. Free accounts can sustain 120 requests per minute per account with a burst capacity of 60. Free bulk traffic is additionally limited to 20 requests per minute per account across all bulk endpoints and 100 per minute per IPv4 address or IPv6 /56 network. Paid accounts can sustain 600 requests per minute with a burst capacity of 120.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Plan:
          schema:
            type: string
            enum:
            - free
            - paid
          description: The account plan whose policy was applied.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The immediate burst capacity, or the active bulk fixed-window limit when a bulk-specific limit is exceeded.
        X-RateLimit-Remaining:
          schema:
            type: integer
            example: 0
          description: Immediate burst tokens remaining, or requests remaining in the active bulk fixed window.
        X-RateLimit-Policy:
          schema:
            type: string
          description: Machine-readable summary of the active tier and limit policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: RATE_LIMITED
              message: Rate limit exceeded. Please wait before making more requests.
  schemas:
    ApiPricingResponse:
      type: object
      description: API credit pricing information
      properties:
        currency:
          type: string
          example: credits
        signup_bonus:
          type: integer
          description: Credits given on signup
        monthly_refresh:
          type: string
          description: Monthly credit refresh policy
        endpoints:
          type: array
          items:
            type: object
            properties:
              endpoint:
                type: string
              method:
                type: string
                enum:
                - GET
                - POST
                - PUT
                - DELETE
                - PATCH
              credits:
                type: integer
              variants:
                type: array
                items:
                  type: object
                  properties:
                    parameter:
                      type: string
                    equals: {}
                    credits:
                      type: integer
              bulk_pricing:
                type: object
                properties:
                  per_item_rate:
                    type: integer
                  formula:
                    type: string
                  min_cost:
                    type: integer
              note:
                type: string
        free_endpoints:
          type: array
          items:
            type: string
        note:
          type: string
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code for programmatic handling
              example: INVALID_DOMAIN
            type:
              type: string
              enum:
              - authentication_error
              - credits_error
              - permission_error
              - not_found_error
              - conflict_error
              - rate_limit_error
              - timeout_error
              - validation_error
              - upstream_error
              - api_error
              - request_error
              description: Stable error category used by official SDK subclasses
            message:
              type: string
              description: Human-readable error message
              example: Invalid domain format
            status:
              type: integer
              minimum: 400
              maximum: 599
              description: HTTP status repeated in the JSON error for queue and log processors
            retryable:
              type: boolean
              description: Whether retrying can be appropriate after applying retry guidance
            request_id:
              type: string
              description: Request identifier matching the X-Request-Id response header
            suggestion:
              type: string
              description: Suggestion for fixing the error
            details:
              type: object
              description: Optional structured context for the error
              additionalProperties: true
            retry_after:
              type: integer
              minimum: 0
              description: Seconds to wait before retrying when the error is temporary
              example: 300
            docs_url:
              type: string
              description: Link to relevant documentation
              example: /docs#parameters
          required:
          - type
          - code
          - message
          - status
          - retryable
          - request_id
          - docs_url
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key for authentication. Get yours free at https://domscan.net. Also accepts Authorization: Bearer header.'
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: Active DomScan browser session. Used by account-management endpoints.
externalDocs:
  description: Full API Documentation
  url: https://domscan.net/docs
x-rapidapi-product: domscan
x-domscan-rate-limits:
  free:
    general:
      scope: account
      sustained_requests_per_minute: 120
      burst_capacity: 60
      shared_across_api_keys_and_sessions: true
    bulk:
      scope: all bulk endpoints combined
      account_requests_per_minute: 20
      network_requests_per_minute: 100
      ipv6_network_prefix: 56
  paid:
    general:
      scope: API key for key-authenticated requests; IP for browser sessions
      sustained_requests_per_minute: 600
      burst_capacity: 120
    free_bulk_budget_applies: false
  response:
    status: 429
    retry_header: Retry-After
    headers_on_every_authenticated_response:
    - X-RateLimit-Plan
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    - X-RateLimit-Policy
    burst_headers:
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    policy_header: X-RateLimit-Policy
x-domscan-response-metadata:
  compatibility: additive response headers; established JSON success bodies are unchanged
  headers:
    X-Request-Id: Unique request identifier for logs and support
    X-API-Version: DomScan API release version
    X-Response-Time: Server processing duration in milliseconds
    X-Credits-Requested: Credits requested before refund settlement
    X-Credits-Charged: Credits retained after settlement
    X-Credits-Refunded: Credits returned during settlement
    X-Credits-Remaining: Authenticated account balance after the request
    X-Data-Freshness: fresh, cached, stale, mixed, or unknown
    X-RateLimit-Limit: Active burst capacity
    X-RateLimit-Remaining: Remaining burst capacity
    X-RateLimit-Plan: Active plan, or not_applicable before authentication
    X-RateLimit-Policy: Machine-readable active rate policy