openapi: 3.1.0
info:
  title: Intelx.io - Live Search API
  license:
    name: Kleissner Investments v1.0
    url: 'https://intelx.io/licenses/LICENSE-1.0'
  version: 1.0.0
  description: |
    Internal search in "buckets" (e.g. usenet, web.public, whois).   Needs `X-Key` header authorization.
servers:
  - url: 'https://3.intelx.io'
paths:
  /authenticate/info:
    get:
      summary: Return a JSON object with the current user's API capabilities
      operationId: authenticateInfo
      description: |
        Return a JSON object with the current user's API capabilities
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              example:
                added: "2025-11-04T22:45:01.1220324Z"
                buckets: ["darknet","dns","documents.public","dumpster","leaks.logs","leaks.private","leaks.public","pastes","usenet","web.gov.ru","web.public","whois"]
                bucketsh: ["Darknet","DNS","Documents » Public","Dumpster","Leaks » Logs","Leaks » Restricted","Leaks » Public","Pastes","Usenet","Web » Government » Ukraine","Web » Public","Whois"]
                preview: []
                previewh: []
                redacted: []
                redactedh: []
                paths:
                  /authenticate/info: { Path: "/authenticate/info", Credit: 0, CreditMax: 0, CreditReset: 0 }
                  /file/preview:       { Path: "/file/preview",       Credit: 9971, CreditMax: 10000, CreditReset: 2 }
                  /file/read:          { Path: "/file/read",          Credit: 998,  CreditMax: 1000,  CreditReset: 2 }
                  /file/treeview:      { Path: "/file/treeview",      Credit: 500,  CreditMax: 500,   CreditReset: 2 }
                  /file/view:          { Path: "/file/view",          Credit: 998,  CreditMax: 1000,  CreditReset: 2 }
                  /intelligent/search: { Path: "/intelligent/search", Credit: 479,  CreditMax: 500,   CreditReset: 2 }
                  /intelligent/search/export:  { Path: "/intelligent/search/export",  Credit: 100, CreditMax: 100, CreditReset: 2 }
                  /intelligent/search/result:  { Path: "/intelligent/search/result",  Credit: 0,   CreditMax: 0,   CreditReset: 0 }
                  /intelligent/search/statistic: { Path: "/intelligent/search/statistic", Credit: 0,  CreditMax: 0,   CreditReset: 0 }
                  /intelligent/search/terminate: { Path: "/intelligent/search/terminate", Credit: 0,  CreditMax: 0,   CreditReset: 0 }
                  /item/selector/list/export:  { Path: "/item/selector/list/export",  Credit: 1000, CreditMax: 1000, CreditReset: 2 }
                  /item/selector/list/human:   { Path: "/item/selector/list/human",   Credit: 1000, CreditMax: 1000, CreditReset: 2 }
                  /phonebook/search:           { Path: "/phonebook/search",           Credit: 100,  CreditMax: 100,  CreditReset: 2 }
                  /phonebook/search/export:    { Path: "/phonebook/search/export",    Credit: 100,  CreditMax: 100,  CreditReset: 2 }
                  /phonebook/search/result:    { Path: "/phonebook/search/result",    Credit: 0,    CreditMax: 0,    CreditReset: 0 }
                searchesactive: 0
                maxconcurrentsearches: 10
        401:
          description: Unauthorized
  /file/preview:
    get:
      summary: File preview
      operationId: filePreview
      description: File preview
      security:
        - ApiKeyQueryParam: []
      parameters:
        - name: sid
          in: query
          required: true
          style: form
          schema:
            type: string
          example: 'fb054e59c7eecab877b317d1f4204abbe4130c727a15ea6e2555e1ebdcd63540b54ecd3242a0a77f70a7e57a4dfc9b70712cfc80f3757beda93e3fc657b41ee7'
        - name: f
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: integer
          description: Format
        - $ref: '#/components/parameters/LAsLimitParam'
        - name: c
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: integer
            enum: [ 1, 2, 3, 4 ]
          description: Data type
        - name: m
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: integer
          description: Media
        - name: b
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: string
          example: web.public.we
          description: Bucket
  /file/read:
    get:
      summary: Read a file's raw contents. Use this for direct data download.
      operationId: fileRead
      description: |
        id option:
          - Specifies the item's system ID to read.
    
        type option:
          - Specifies content disposition or not.
          - 0: No content disposition. Returns raw binary file.
          - 1: Content disposition. May fix line endings to CR LF for text files.
    
        bucket option:
          - Bucket is required.
    
        name option:
          - Specify the name to save the file as (e.g document.pdf).
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
        - name: type
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          description: |
            Types:  
                0 = Raw binary
                1 = Raw binary with content disposition and optional file &name=[name] as parameter
                2 = Text view, any non-printable characters shall be removed, UTF-8 encoding. Optional max &size=[number] as parameter.
                3 = Hex view of data. Optional max &size=[number] as parameter.
                4 = Auto-detect hex view or text view. Optional max &size=[number] as parameter.
                    The default max size if none is specified is 1 MB.
        - name: name
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: string
          description: |
            Types:  
                1 = Raw binary with content disposition and optional file &name=[name] as parameter
        - name: size
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: integer
          description: |
            Optional max &size=[number] as parameter.
            The default max size if none is specified is 1 MB.
        - name: storageid
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          description: Either the storage identifier or system identifier has to be specified.
        - name: systemid
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          description: Either the storage identifier or system identifier has to be specified.
      responses:
        "200":
          description: OK
        "404": 
          description: item was not found
        "503":
          description: no storage server was available
  /intelligent/search/export:
     get:
       operationId: intelligent/search/export
       summary: Export intelligent search
       security:
         - ApiKeyQueryParam: [ ]
       parameters:
         - $ref: '#/components/parameters/SearchIdParam'
         - $ref: '#/components/parameters/LAsLimitParam'
         - name: f
           in: query
           required: false
           style: form
           explode: true
           schema:
             type: integer
           description: Format
       responses:
         "200":
           description: OK
         "404":
           description: item was not found
  /intelligent/search/result:
     get:
       summary: Fetch intelligent search result
       operationId: intelligentSearchResult
       security:
         - ApiKeyQueryParam: [ ]
       parameters:
        - $ref: '#/components/parameters/SearchIdParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/MediaParam'
        - name: statistics
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: integer
          description: Add statistics
        - name: previewlines
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: integer
          description: Preview lines count
        - $ref: '#/components/parameters/OneBucketParam'
        - name: dateFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2024-01-01 00:00:00'
            pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
          description: Date from of the result in `YYYY-mm-dd HH:ii:ss` format. (Not RFC3339)
        - name: dateTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2024-01-31 23:59:59'
            pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
          description: Date to of the result in `YYYY-mm-dd HH:ii:ss` format. (Not RFC3339)
        - name: reset
          in: query
          required: false
          schema:
            type: integer
            enum: [0, 1]
          description: Reset previous searches
  /intelligent/search/statistic:
    get:
      summary: Intelligent search statistics
      operationId: intelligentSearchStatistics
      security:
        - ApiKeyQueryParam: [ ]
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
  /intelligent/search/terminate:
    get:
      summary: Terminate previous search
      operationId: intelligentSearchTerminate
      security:
        - ApiKeyQueryParam: [ ]
      parameters:
       - $ref: '#/components/parameters/SearchIdParam'
  /item/selector/list:
    get:
      summary: Lists all selectors for an item
      operationId: itemSelectorList
      description: lists all selectors for an item from the first selector service that responds.
      security:
        - ApiKeyAuth: [ ]
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
      responses:
        '200':
          description: Success search
        '400':
          description: if invalid input id
        '404':
          description: item not found
  /item/selector/list/human:
     get:
       operationId: selectorListHumanReadable
       summary: Lists all selectors for an item with human translation
       description: Lists all selectors for an item from the first selector service that responds with human translation.
       security:
         - ApiKeyQueryParam: [ ]
       parameters:
         - $ref: '#/components/parameters/SearchIdParam'
         - $ref: '#/components/parameters/OneBucketParam'
       responses:
         '200':
           description: with JSON structure SelectorLink
         '400':
           description: if invalid input id
         '404':
           description: item not found
  /item/selector/list/export:
    get:
      summary: Exports all selectors for an item
      operationId: itemSelectorListExport
      description: |
        Exports all selectors for an item from the first selector service that responds with human translation as CSV.
        CSV header: Item System ID, Selector, Selector Type, Selector Type Human
        Filename:   "Selectors [System ID].csv"
      security:
       - ApiKeyQueryParam: [ ]        
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
      responses:
        '200':
          description: with the data, Content-Disposition set
        '204':
          description: item unavailable. This prevents redirection of the user to error page when providing a direct download link.
        '400':
          description: invalid input
  /phonebook/search:
    post:
      operationId: phonebookSearch
      summary: Phonebook search
      security:
        - ApiKeyAuth: [ ]
      parameters:
        - name: term
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          example: info@intelx.io
        - name: target
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: integer
            enum: [ 0, 1, 2, 3 ]
            description: |
              Search Phonebook:
              - 0: All
              - 1: Domains
              - 2: Email Addresses
              - 3: URLs
        - $ref: '#/components/parameters/BucketsParam'
        - $ref: '#/components/parameters/MaxresultsParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - $ref: '#/components/parameters/MediaParam'
        - $ref: '#/components/parameters/TerminateParam'
  /phonebook/search/export:
    get:
      operationId: phonebookSearchExport
      summary: Export
      security:
        - ApiKeyQueryParam: [ ]
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
        - $ref: '#/components/parameters/LAsLimitParam'
  /phonebook/search/result:
    get:
      operationId: phonebookSearchResult
      summary: Fetch phonebook search result
      security:
        - ApiKeyQueryParam: [ ]
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
        - $ref: '#/components/parameters/LAsLimitParam'
  /api/item/get:
    get:
      operationId: apiItemGet
      summary: Get item meta-data
      security:
        - ApiKeyQueryParam: [ ]
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
  /api/item/get/human:
    get:
      operationId: apiItemGetHumanReadable
      summary: Get item meta-data with human translation
      security:
        - ApiKeyQueryParam: [ ]
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
  /intelligent/search:
    post:
      summary: Initialize an intelligent search and return the ID of the task/search for further processing.
      operationId: intelligentSearch
      description: |
        Initialize an intelligent search and return the ID of the task/search for further processing.         
      parameters:
        - name: selector
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          example: info@intelx.io
          description: |
            The term must be a strong selector. These selector types are currently supported:
              - Email address
              - Domain, including wildcards like *.example.com
              - URL
              - IPv4 & IPv6
              - CIDRv4 & CIDRv6
              - Phone Number
              - Bitcoin Address
              - MAC Address
              - IPFS Hash
              - UUID
              - Storage ID
              - System ID
              - Simhash
              - Credit card number
              - IBAN

            Soft selectors (generic terms) are not supported!
        - $ref: '#/components/parameters/MaxresultsParam'
        - $ref: '#/components/parameters/BucketsParam'
        - $ref: '#/components/parameters/TimeoutParam'
        - name: datefrom
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          example: 2020-01-01 00:00:00        
          description: |
            - Set a starting date to begin the search from.
            - Example: 2020-01-01 00:00:00
            - Example: 2020-01-01 12:00:00
        - name: dateto
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          example: 2020-02-02 23:59:59
          
          description: |
            - Set an ending date to finish the search from.
            - Example: 2020-02-02 23:59:59
            - Example: 2020-02-02 00:00:00
        - name: sort
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: integer
          example: 4
          description: |
            - Define the way to sort search results.
            - 0: No sorting.
            - 1: X-Score ASC. Least relevant items first.
            - 2: X-Score DESC. Most relevant items first.
            - 3: Date ASC. Oldest items first.
            - 4: Date DESC. Newest items first.
        - $ref: '#/components/parameters/MediaParam'
        - name: lookuplevel
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: integer
          example: 0
          description: |
            lookuplevel
        - $ref: '#/components/parameters/TerminateParam'
      responses:
        '200':
          description: Success search
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: Result status
                  id:
                    type: string
                    example: '61202067-543e-4e6a-8c23-11f9b8f008cf'
                    pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
          links:
            LiveSearchResult:
              operationId: liveSearchResult
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid data
        '401':
          description: Invalid api token
      security:
        - ApiKeyAuth: []
  /live/search/internal:
    get:
      summary: Internal live search
      operationId: liveSearch
      description: |
        Initiates the search; will return status and search Id on success.
      parameters:
        - name: selector
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: string
          example: info@intelx.io
          description: Search term
        - $ref: '#/components/parameters/OneBucketParam'
        - name: skipinvalid
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Skip invalid records
        - $ref: '#/components/parameters/LimitParam'
        - name: analyze
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Analyze
        - name: datefrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2024-01-01 00:00:00'
            pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
          description: Date from of the result in `YYYY-mm-dd HH:ii:ss` format. (Not RFC3339)
        - name: dateto
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2024-01-31 23:59:59'
            pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$'
          description: Date to of the result in `YYYY-mm-dd HH:ii:ss` format. (Not RFC3339)
        - $ref: '#/components/parameters/TerminateParam'
      responses:
        '200':
          description: Success search
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: Result status
                  id:
                    type: string
                    example: '61202067-543e-4e6a-8c23-11f9b8f008cf'
                    pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
          links:
            LiveSearchResult:
              operationId: liveSearchResult
              parameters:
                id: $response.body#/id
        '400':
          description: Invalid data
        '401':
          description: Invalid api token
      security:
        - ApiKeyAuth: []
  /live/search/result:
    get:
      summary: Fetch results from internal live search
      operationId: liveSearchResult
      description: |
        Initiates the search; will return status and search Id on success. Status = 2 means end of search result. Good manners is to wait 1s before each new result fetch.
      parameters:
        - $ref: '#/components/parameters/SearchIdParam'
        - name: format
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: |
            Format Info 0 Text view, any non-printable characters shall be removed, UTF-8 encoding. 1 Hex view of data. 2 Auto-detect hex view or text view. 3 Picture view. 4 Not supported. 5 HTML inline view. Content will be sanitized and modified! 6 Text view of PDF. Content will be automatically converted. 7 Text view of HTML. 8 Text view of Word files (DOC/DOCX/RTF).
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Success search
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    enum: [ 0, 1, 2 ]
                    description: Result status
                      0,1 - there is another result/s to fetch
                      2 - no more results
                  results:
                    type: string
                    description: Text response
        '400':
          description: Invalid data
        '401':
          description: Invalid api token
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyQueryParam:
      type: apiKey
      in: query
      name: k
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Key
  parameters:
    TimeoutParam:
      name: timeout
      in: query
      required: true
      style: form
      explode: true
      schema:
        type: integer
      example: 30
      description: |
        - Set a timeout value for the search.
    MediaParam:
      name: media
      in: query
      required: true
      style: form
      explode: true
      schema:
        type: integer
      example: 0
      description: |
        - Define the type of media to search for.
        - 0: Not set. (All media types)
        - 1: Paste document
        - 2: Paste User
        - 3: Forum
        - 4: Forum Board
        - 5: Forum Thread
        - 6: Forum Post
        - 7: Forum User
        - 8: Screenshot of a Website
        - 9: HTML copy of a website.
        - 10: Invalid, do not use.
        - 11: Invalid, do not use.
        - 12: Invalid, do not use.
        - 13: Tweet
        - 14: URL, high-level item having HTML copies as linked sub-items
        - 15: PDF document
        - 16: Word document
        - 17: Excel document
        - 18: Powerpoint document
        - 19: Picture
        - 20: Audio file
        - 21: Video file
        - 22: Container files including ZIP, RAR, TAR and others
        - 23: HTML file
        - 24: Text file
    TerminateParam:
      name: terminate
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
      description: You can terminate previous search ids
    MaxresultsParam:
      name: maxresults
      in: query
      required: true
      style: form
      explode: true
      schema:
        type: integer
      example: 100
      description: |
        - Tells how many results to query maximum per bucket.
    BucketsParam:
      name: buckets
      in: query
      required: false
      style: form
      explode: true
      schema:
        type: string
      example: pastes,darknet.i2p
      description: |
        - Specify the buckets to search
        - Example: buckets=[]
        - Example: buckets=['pastes', 'darknet.i2p']
    OneBucketParam:
      name: bucket
      in: query
      required: false
      style: form
      explode: true
      schema:
        type: string
      example: darknet.i2p
      description: |
        - Specify the bucket to search
    LimitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
      description: Result limit
    LAsLimitParam:
      name: l
      in: query
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
      description: Result limit
    SearchIdParam:
      name: id
      in: query
      required: true
      style: form
      explode: true
      schema:
        type: string
        pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
      example: '61202067-543e-4e6a-8c23-11f9b8f008cf'
      description: 'Search id (e.g. "61202067-543e-4e6a-8c23-11f9b8f008cf")'