openapi: 3.2.0
info:
  title: HackNotice Research Service Accounts API
  version: '2026-08-22'
  summary: External threat-intelligence API for first-party, third-party and end-user breach monitoring, threat research and vendor assessments.
  description: 'HackNotice''s REST API over its external threat-intelligence platform: credential and breach alerts for first-party domains, third-party vendors and end users; dark-web / hacker-forum research search; and AI-assisted vendor security assessments.


    PROVENANCE: this document was DERIVED by API Evangelist from HackNotice''s own published Postman collection "HackNotice-API", reached at https://api-docs.hacknotice.com (HTTP 301 -> https://documenter.getpostman.com/view/806684/2sBXiri7pT), linked from HackNotice''s help centre article "API". Paths, methods, parameters, request bodies and tags are transcribed from that collection; nothing was invented. Concrete record ids in the collection''s example URLs were templated into path parameters, and every token-shaped example value was redacted.


    HackNotice publishes a rate limit of 1 query per second, and states that API access is granted to approved accounts only after a 30-minute consultation call.'
  termsOfService: https://hacknotice.com/businesstandc/
  contact:
    name: HackNotice Support
    url: https://hacknotice.zendesk.com/hc/en-us
    email: support@hacknotice.com
  x-api-evangelist-derived-from: https://api-docs.hacknotice.com
servers:
- url: https://extensionapi.hacknotice.com
  description: HackNotice production API host, as declared by HackNotice's own first-party n8n node (API_BASE_URL in credentials/HackNoticeApi.credentials.ts, github.com/HackNotice/n8n-nodes-hacknotice). The published Postman collection ships an internal {{url}} variable pointing at a developer VPN host, which is not the production base.
security:
- jwtAuth: []
- apiKeyAuth: []
tags:
- name: Research Service Accounts
  description: Threat-research search over terms, filenames and word pools, plus saved searches.
paths:
  /research/count/filename/term:
    post:
      tags:
      - Research Service Accounts
      summary: Count search filename term
      operationId: postCountSearchFilenameTerm
      parameters:
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                term:
                  type: string
                  description: Any search word or phrase
                searchtype:
                  type: string
                  description: 'Search type: match_phrase, wildcard_pre, wildcard_post, wildcard_both. If no or incorrect type is given, defaults to match_phrase.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /research/count/pool:
    post:
      tags:
      - Research Service Accounts
      summary: Count word pool
      operationId: postCountWordPool
      parameters:
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                searchtype:
                  type: string
                pool:
                  type: array
                match:
                  type: string
            example:
              searchtype: word_pool
              pool:
              - '1600'
              - pennsylvania
              - washington
              match: '3'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /research/count/term:
    post:
      tags:
      - Research Service Accounts
      summary: Count search term
      operationId: postCountSearchTerm
      parameters:
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                term:
                  type: string
                  description: Any search word or phrase
                searchtype:
                  type: string
                  description: 'Search type: match_phrase, wildcard_pre, wildcard_post, wildcard_both. If no or incorrect type is given, defaults to match_phrase.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /research/search/filename/term/page/{pageNum}:
    post:
      tags:
      - Research Service Accounts
      summary: Search filename term and page
      operationId: postSearchFilenameTermAndPage
      parameters:
      - name: pageNum
        in: path
        required: true
        schema:
          type: integer
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                term:
                  type: string
                  description: Any search word or phrase
                searchtype:
                  type: string
                  description: 'Search type: match_phrase, wildcard_post. If incorrect type is given, defaults to match_phrase.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /research/search/pool/page/{pageNum}:
    post:
      tags:
      - Research Service Accounts
      summary: Search word pool and page
      operationId: postSearchWordPoolAndPage
      parameters:
      - name: pageNum
        in: path
        required: true
        schema:
          type: integer
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                searchtype:
                  type: string
                pool:
                  type: array
                match:
                  type: string
                startdate:
                  type: string
                enddate:
                  type: string
                fullrecords:
                  type: boolean
            example:
              searchtype: word_pool
              pool:
              - first
              - second
              match: '2'
              startdate: '2015-04-03'
              enddate: '2022-07-30'
              fullrecords: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /research/search/term/page/{pageNum}:
    post:
      tags:
      - Research Service Accounts
      summary: Search term and page
      operationId: postSearchTermAndPage
      parameters:
      - name: pageNum
        in: path
        required: true
        schema:
          type: integer
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                term:
                  type: string
                  description: Any search word or phrase
                searchtype:
                  type: string
                  description: 'Search type: match_phrase, wildcard_pre, wildcard_post, wildcard_both. If incorrect type is given, defaults to match_phrase.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /researchsavedsearch/count:
    get:
      tags:
      - Research Service Accounts
      summary: Get the count of documents
      operationId: getTheCountOfDocuments3
      description: 'Folder: Research Saved Search. Read a count of all documents.'
      parameters:
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /researchsavedsearch/create:
    post:
      tags:
      - Research Service Accounts
      summary: Create a doc
      operationId: postCreateADoc2
      description: 'Folder: Research Saved Search. Add a document to your documents.'
      parameters:
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                search:
                  type: string
                endpoint:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /researchsavedsearch/page/{pageNum}:
    get:
      tags:
      - Research Service Accounts
      summary: Read a page of documents
      operationId: getReadAPageOfDocuments3
      description: 'Folder: Research Saved Search. Read all documents.'
      parameters:
      - name: pageNum
        in: path
        required: true
        schema:
          type: integer
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /researchsavedsearch/runsearch/{documentId}:
    get:
      tags:
      - Research Service Accounts
      summary: Run search a doc
      operationId: getRunSearchADoc
      description: 'Folder: Research Saved Search. Run a document by the document ID.'
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: string
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /researchsavedsearch/search:
    post:
      tags:
      - Research Service Accounts
      summary: Search for a search name
      operationId: postSearchForASearchName
      description: 'Folder: Research Saved Search. Search your documents for a search name.'
      parameters:
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                term:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
  /researchsavedsearch/{documentId}:
    get:
      tags:
      - Research Service Accounts
      summary: Read a doc
      operationId: getReadADoc3
      description: 'Folder: Research Saved Search. Get a document by the document ID.'
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: string
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
    put:
      tags:
      - Research Service Accounts
      summary: Update a doc
      operationId: putUpdateADoc2
      description: 'Folder: Research Saved Search. Update a document by the document ID.'
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: string
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
    delete:
      tags:
      - Research Service Accounts
      summary: Delete a doc
      operationId: deleteADoc3
      description: 'Folder: Research Saved Search. Remove a document by the document ID.'
      parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: string
      - name: apikey
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized — missing or invalid JWT / API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - jwtAuth: []
      - apiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      description: HackNotice error envelope observed on the live API hosts.
      properties:
        message:
          type: string
          description: Human-readable error message, e.g. "Unauthorized user!" or "Not found".
  securitySchemes:
    jwtAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Session token from POST /auth/sign_in, sent as the literal prefix "JWT " followed by the token — e.g. Authorization: JWT <token>. Note this is HackNotice''s own scheme, not RFC 6750 Bearer.'
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: Per-account API key issued by HackNotice, sent in the lower-case "apikey" header alongside the JWT on most operations.
    integrationKeyAuth:
      type: apiKey
      in: header
      name: X-HackNotice-Integration-Key
      description: Per-user HackNotice integration secret (hn_ik_ prefix). Single-header alternative to apikey + email + password; also the credential used by the HackNotice MCP server.