openapi: 3.1.0
info:
  title: DomainHelp Agentic DNS Skills
  version: 1.0.0
  description: Initial open DNS and domain utilities for humans, LLMs, and agents.
externalDocs:
  description: DomainHelp DNS Skills documentation
  url: https://dnsskills.md/skills
servers:
  - url: https://app.domainhelp.com
    description: DomainHelp execution API
paths:
  /api/v1/skills:
    get:
      summary: List DomainHelp agentic skills
      operationId: listDomainHelpSkills
      responses:
        '200':
          description: Skill catalog
          content:
            application/json:
              schema:
                type: object
  /api/v1/whatismypublicip:
    get:
      summary: Return the public IP address observed by DomainHelp
      operationId: whatIsMyPublicIp
      parameters:
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, text]
      responses:
        '200':
          description: Public IP result
          content:
            application/json:
              schema:
                type: object
                properties:
                  skill:
                    type: string
                  ip:
                    type: string
                  observed_at:
                    type: string
                    format: date-time
            text/plain:
              schema:
                type: string
  /api/v1/isconfusable:
    get:
      summary: Analyze an IDN, punycode value, domain, label, or string for homoglyph risk
      operationId: getIsConfusable
      parameters:
        - name: input
          in: query
          required: true
          schema:
            type: string
            maxLength: 512
      responses:
        '200':
          description: Homoglyph analysis result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomoglyphAnalysis'
        '422':
          description: Invalid input
    post:
      summary: Analyze an IDN, punycode value, domain, label, or string for homoglyph risk
      operationId: postIsConfusable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input:
                  type: string
                  maxLength: 512
      responses:
        '200':
          description: Homoglyph analysis result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomoglyphAnalysis'
        '422':
          description: Invalid input
  /api/v1/myresolver/check:
    post:
      summary: Create a resolver detection token and lookup hostname
      operationId: createMyResolverCheck
      responses:
        '201':
          description: Resolver check created
          content:
            application/json:
              schema:
                type: object
  /api/v1/myresolver/result:
    get:
      summary: Poll for a resolver detection result
      operationId: getMyResolverResult
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Resolver result or pending status
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Token not found
        '410':
          description: Token expired
  /api/v1/spfflattener:
    post:
      summary: Resolve SPF includes and produce a flattened SPF record
      operationId: postSpfFlattener
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain]
              properties:
                domain:
                  type: string
                  maxLength: 255
      responses:
        '200':
          description: SPF flattening result
          content:
            application/json:
              schema:
                type: object
                properties:
                  skill:
                    type: string
                  version:
                    type: string
                  domain:
                    type: string
                  result:
                    type:
                      - string
                      - 'null'
                  stages:
                    type: array
                    items:
                      type: object
                  finalSPFRecord:
                    type:
                      - string
                      - 'null'
                  error:
                    type:
                      - string
                      - 'null'
        '422':
          description: Invalid domain, no SPF record, or DNS/SPF flattening error
  /api/v1/dnstwister:
    post:
      summary: Generate and inspect lookalike domain permutations
      operationId: postDnsTwister
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain]
              properties:
                domain:
                  type: string
      responses:
        '200':
          description: DNS Twister result
          content:
            application/json:
              schema:
                type: object
                properties:
                  skill:
                    type: string
                  version:
                    type: string
                  domain:
                    type: string
                  rows:
                    type: array
                    items:
                      type: object
                  output:
                    type:
                      - string
                      - 'null'
        '422':
          description: Invalid domain
        '500':
          description: DNS Twister backend execution failed
components:
  schemas:
    HomoglyphAnalysis:
      type: object
      properties:
        input:
          type: string
        normalized_input:
          type: string
        is_idn:
          type: boolean
        input_kind:
          type: string
        input_type:
          type: string
        a_label:
          type:
            - string
            - 'null'
        u_label:
          type: string
        ascii_only:
          type: boolean
        is_confusable:
          type: boolean
        confusable_class:
          type: string
        scripts_detected:
          type: array
          items:
            type: string
        likely_mimics:
          type: array
          items:
            type: object
        confusable_characters:
          type: array
          items:
            type: object
        explanation:
          type: string
        risk_level:
          type: string
