openapi: 3.0.3
info:
  title: Columbus API
  description: |
    A fast, API-first subdomain discovery service with advanced queries.
    
    The `Access-Control-Allow-Origin` header on the API endpoints is always set to `*` to allow integration into other sites.
  contact:
    email: columbus@elmasy.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: dev
servers:
  - url: https://columbus.elmasy.com
tags:
  - name: domain
    description: Lookup domain.
  - name: info
    description: Server informations.
  - name: tools
    description: Helper APIs.

paths:
  /api/lookup/{domain}:
    get:
      tags:
        - domain
      operationId: GetLookup
      summary: Lookup subdomains for domain.
      description: |
      
        Returns an array of subdomains.

        The response contains the subdomains only, the domain not included (eg.: `["one", "two", ...]`).
        
        If a FQDN is requested than the domain name will be taken out and used in the lookup (eg.: `/api/lookup/columbus.elmasy.com` will be the same as `/api/lookup/elmasy.com`)
        
        If `Accept` header is set to `text/plain`, this endpoint returns a newline delimetered text of the list (eg.: `one\ntwo\nthree`).
        
        # Note
        - The subdomain part will be trimmed (eg.: `/api/lookup/totally.invalid.elmasy.com` will be the same as `/api/lookup/elmasy.com`).
        - If `domain` not found, the server saves for later process.
        - Only the subdomains are sent in the response to save CPU and RAM on the server side and save bandwith on both client- and server-side.
      parameters:
        - name: domain
          in: path
          description: Domain to get the subdomains.
          required: true
          schema:
            type: string
        - name: days
          in: query
          description:  | 
            - If `days` greater than 0, returns subdomains that has a valid DNS record in the last `days` days.
            - If `days` is 0, returns subdomains that has a valid DNS record regardless of the age.
            - If `days` is -1, returns every known subdomains.

            If omitted, returns every subdomain including historical and invalid ones (aka the default `days` is -1). 
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringArray'
              example:
                summary: success
                description: Request is sucessful
                externalValue: 
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '400':
          description: Invalid domain or days
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.

  /api/starts/{domain}:
    get:
      tags:
        - domain
      operationId: GetStarts
      summary: Find domains that start with the given string.
      description: |
      
        Return an array of Second Level Domains thats start with `domain`.
        
        The `domain` parameter must be a Second Level Domain (eg.: `example`) 
        
        Example: `/api/starts/reddit` returns `["reddit", "redditmedia", "redditstatistic", ...]`.
        
        If `Accept` header is set to `text/plain`, this endpoint returns a newline delimetered text of the list.
        
        # Note
        - The `domain`'s length mist be greater than 4 character.
        - Only the SLDs are sent in the response to save CPU and RAM on the server side and save bandwith on both client- and server-side.

      parameters:
        - name: domain
          in: path
          description: Domain to get the TLDs.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringArray'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '400':
          description: Invalid domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.
  
  /api/tld/{domain}:
    get:
      tags:
        - domain
      operationId: GetTLD
      summary: Find TLDs for the given domain.
      description: |
      
        Returns a list of all known Top Level Domains for the given domain.
        
        The domain parameter must be a Second Level Domain (eg.: example).
        
        Example: `/api/tld/example` returns `["com", "org", "net"]`.
        
        If `Accept` header is set to `text/plain`, this endpoint returns a newline delimetered text of the list (eg.: `com\norg\nnet`).
        
      parameters:
        - name: domain
          in: path
          description: Domain to get the TLDs.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringArray'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '400':
          description: Invalid domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '404':
          description: Domain not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.
          
  /api/history/{domain}:
    get:
      tags:
        - domain
      operationId: GetHistory
      summary: DNS record history.
      description: |
    
        Returns the DNS history for the given domain and its subdomains.
        
        The `type` codes can be found here: [https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml](https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml).
        
        The `time` field is the time in Unix timestamp when the record last seen.
        
        # Note
        - **EXPERIMENTAL FEATURE!**
        - The subdomain part will be trimmed (eg.: `/api/history/totally.invalid.elmasy.com` will be the same as `/api/lookup/elmasy.com`).
        - If `domain` not found, the server saves for later process.
      parameters:
        - name: domain
          in: path
          description: Domain to search.
          required: true
          schema:
            type: string
        - name: days
          in: query
          description:  | 
            - If `days` greater than 0, returns domains that has a valid DNS record in the last `days` days.
            - If `days` is 0 or -1, returns domains that has a valid DNS record regardless of the age.
            - If `days` is -1, returns every known domain with possible empty records.

            If omitted, returns every records (aka the default `days` is -1).
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/History'
        '400':
          description: Invalid domain or days
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No records found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.

  /api/insert/{domain}:
    put:
      tags:
        - domain
      operationId: PutAPIInsert
      summary: Insert domain into the database.
      description: |
        This endpoint technically suggest a domain to the server.
        
        It is required to have at least one valid DNS record for the domain to insert (eg.: `A` or `AAAA`).
        The domain is sent to an underlying channel, so returns fast, but the client will not get informed about the result.
        If the underlying channel is full, hangs until there is free space to send.
        
        This endpoint uses blacklist and rate limiter to prevent garbage and resource exhaustion
        (eg.: sending invalid domain results a block for some time).
      parameters:
        - name: domain
          in: path
          description: Domain to insert.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '400':
          description: Invalid domain.
        '403':
          description: Client IP blocked.
        '500':
          description: Internal Server Error.
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.
          
  /api/stat:
    get:
      tags:
        - info
      summary: Basic domain statistic
      operationId: GetStatistics
      description: |
        Basic domain statistic that holds the total number of domains and
        the total number of valid domains.
        
        Fields:
        - The `date` field is the last update date in Unix time format.
        - The `total` field is the number of total entries in the database.
        - The `updated` field is the number of total entries updated (including entries that updated, but no valid DNS record found).
        - The `valid` field is the number of total domains that has at least one known DNS record.
        - The `ctlogs` field is an array that holds the stats of the crawled Certificate Transparency Logs.
          - The `name` is the name of the log.
          - The `index` is the current index of the crawler.
          - The `size` is the total number of entries in the log.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stat'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  
  /api/tools/tld/{fqdn}:
    get:
      tags:
        - tools
      operationId: GetToolsTLD
      summary: Get the TLD from a FQDN.
      description: |
        Get the TLD part (eg.: `com`) from a FQDN (eg.: `columbus.elmasy.com`).
        
        **IMPORTANT**: Only ICANN managed TLDs are returned, the private ones are only returned in the Top Level Domain.
        (eg.: `columbus.elmasy.co.uk` -> `co.uk` or `columbus.elmasy.local` -> `local`)
        
        If `Accept` header is `text/plain`, returns the result as a string.
      parameters:
        - name: fqdn
          in: path
          description: FQDN to get the TLD.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '400':
          description: Bad Request. See the error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '404':
          description: Domain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.
                
  /api/tools/domain/{fqdn}:
    get:
      tags:
        - tools
      operationId: GetToolsDomain
      summary: Get the domain from a FQDN.
      description: |
        Get the domain part (eg.: `elmasy.com`) from a FQDN (eg.: `columbus.elmasy.com`).
        
        If `Accept` header is `text/plain`, returns the result as a string.
      parameters:
        - name: fqdn
          in: path
          description: FQDN to get the domain.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '400':
          description: Bad Request. See the error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '404':
          description: Domain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.
  
  /api/tools/subdomain/{fqdn}:
    get:
      tags:
        - tools
      operationId: GetToolsSubdomain
      summary: Get the subdomain from a FQDN.
      description: |
        Get the subdomain part (eg.: `columbus`) from a FQDN (eg.: `columbus.elmasy.com`).
        
        If `Accept` header is `text/plain`, returns the result as a string.
      parameters:
        - name: fqdn
          in: path
          description: FQDN to get the subdomain.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '400':
          description: Bad Request. See the error message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '404':
          description: Subdomain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.
  
  /api/tools/isvalid/{fqdn}:
    get:
      tags:
        - tools
      operationId: GetToolsIsValid
      summary: Returns whether FQDN is a valid domain.
      description: |
        Returns whether FQDN is a valid domain.
      parameters:
        - name: fqdn
          in: path
          description: FQDN to check.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultBool'
            text/plain:
              schema:
                $ref: '#/components/schemas/String'
        '502':
          description: Bad Gateway. Upstream failed.
        '504':
          description: Gateway Timeout. Upstream response takes too long.
        
components:

  schemas:
    StringArray:
      type: array
      items:
        type: string
    String:
      type: string
    Result:
      type: object
      properties:
        result:
          type: string
    ResultBool:
      type: object
      properties:
        result:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
    Stat:
      type: object
      properties:
        date:
          type: integer
        total:
          type: integer
        updated:
          type: integer
        valid:
          type: integer
        ctlogs:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              index:
                type: integer
              size:
                type: integer
    Record:
      type: object
      properties:
        type:
          type: integer
        value:
          type: string
        time:
          type: integer
    Records:
      type: array
      items:
        $ref: '#/components/schemas/Record'
    History:
      type: array
      items:
        type: object
        properties:
          domain:
            type: string
          records:
            $ref: '#/components/schemas/Records'