isMalicious Blocklist API

openapi: 3.2.0
info:
  title: Ismalicious Com Blocklist API
  version: 1.2.0
  contact:
    name: isMalicious Support
    url: https://ismalicious.com/support
    email: contact@ismalicious.com
  license:
    name: Proprietary
    url: https://ismalicious.com/terms
  description: 'Operations tagged blocklist across 2 of this provider''s published API definitions: ismalicious-com-openapi.json, ismalicious-com-openapi2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ismalicious.com
  description: Production server
security:
- ApiKeyAuth: []
- BearerAuth: []
- BasicAuth: []
tags:
- name: Blocklist
  description: Download blocklists and read their generation stats
paths:
  /blocklist/download/{filename}:
    get:
      tags:
      - Blocklist
      summary: Download Blocklist
      description: 'Download a specific blocklist file.


        **Plan Access:**

        - FREE: 10% sample (lite version)

        - BASIC+: Full blocklist


        **Filename pattern** (not an exhaustive list — combinations are generated):

        - `blocklist-{type}-{variant}[-{format}].txt`

        - `type`: `ips` | `domains` | `urls` | `hashes`

        - `variant`: a severity level (`critical`, `high`, `medium`, `low`,

        `all`) or a category (`malware`, `phishing`, `spam`, `scam`, `fraud`,

        `botnet`, `ransomware`, `c2`, `ads`, `tracking`, `abuse`, `attack`,

        `proxy`, `suspicious`, `malicious`, `cryptomining`, `crypto`,

        `adware`, `privacy`, `bruteforce`, `exploit`, `tor`, `vpn`)

        - `format` (optional): `hosts` | `dnsmasq` | `adguard` (plain text when

        omitted)

        - `blocklist-family-{slug}-{type}[-{format}].txt` for malware-family lists

        (e.g. `blocklist-family-emotet-hashes.txt`)


        `GET /blocklist/stats` lists the level/category files currently generated.'
      operationId: downloadBlocklist
      parameters:
      - name: filename
        in: path
        description: 'Blocklist filename — see the operation description for the accepted

          pattern'
        required: true
        schema:
          type: string
        example: blocklist-domains-phishing.txt
      responses:
        '200':
          description: Blocklist file download (text/plain)
        '400':
          description: Invalid blocklist filename
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Plan restriction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Blocklist not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Origin fetch failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.ismalicious.com
      description: Production server
  /blocklist/schedule:
    get:
      tags:
      - Blocklist
      summary: Get Blocklist Schedule
      description: 'When the blocklists are regenerated: the configured interval, the last

        run of the generation job, the newest list''s `lastUpdated`, and when the

        next run is expected. The job runs on an interval placed relative to its

        last run, not at a fixed hour of the day.


        `expectedNextRunAt` is `startedAt + intervalHours` after a `success`, and

        `intervalHours` after the end of a `failed` or `timeout` run. It is

        `null` — the next run cannot be dated from outside the worker — while a run

        is `running`, after an `interrupted` one (the worker retries it shortly

        after its next start), with no run history, or with the scheduler off.

        `overdue` is `true` once now is more than an hour past

        `expectedNextRunAt`.


        **No authentication required.** Not metered.


        **Per-IP ceiling.** 120 requests a minute per IP (per /64 for IPv6),

        shared by `/stats`, `/blocklist/stats`, `/blocklist/schedule`,

        `/analytics`, `/cve/stats/epss`, `/cve/stats/timeseries` and `/license`,

        with or without a key. Over it, `429` with `Retry-After`. Computed on each

        call.'
      operationId: getBlocklistSchedule
      responses:
        '200':
          description: The regeneration schedule
          headers:
            Cache-Control:
              schema:
                type: string
              description: Always `public, max-age=60`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlocklistSchedule'
        '429':
          description: 'Over the per-IP ceiling of the public data routes (120 a minute; `Retry-After`, `X-RateLimit-Type: public`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: 'The schedule could not be read: `{"error": "Blocklist schedule unavailable"}`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - {}
    servers:
    - url: https://api.ismalicious.com
      description: Production server
  /blocklist/stats:
    get:
      tags:
      - Blocklist
      summary: Get Blocklist Stats
      description: 'Get entry counts, last generation timestamps and cache readiness for the

        level- and category-based blocklists. The response is a **map from filename

        to its stats** — there is no wrapper object.


        **No authentication required.**


        **Per-IP ceiling.** 120 requests a minute per IP (per /64 for IPv6),

        shared by `/stats`, `/blocklist/stats`, `/blocklist/schedule`,

        `/analytics`, `/cve/stats/epss`, `/cve/stats/timeseries` and `/license`,

        with or without a key. Over it, `429` with `Retry-After`. An answer can be

        up to a minute old.'
      operationId: getBlocklistStats
      responses:
        '200':
          description: Map from blocklist filename (e.g. `blocklist-ips-critical.txt`) to its stats
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/BlocklistStat'
                propertyNames:
                  type: string
        '429':
          description: 'Over the per-IP ceiling of the public data routes (120 a minute; `Retry-After`, `X-RateLimit-Type: public`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - {}
    servers:
    - url: https://api.ismalicious.com
      description: Production server
  /edl/cve/{id}:
    get:
      tags:
      - Blocklist
      summary: Indicators tagged with one CVE
      operationId: getCveEdl
      parameters:
      - name: id
        in: path
        description: CVE id, `CVE-YYYY-NNNNN`
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: '`ip`, `domain`, `url` or `hash` (default: all, one per line).'
        required: false
        schema:
          type: string
      - name: format
        in: query
        description: '`txt` (default, one indicator per line), `csv` (`indicator,type,cve,lastSeen`) or `json`.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The list (text/plain, text/csv or application/json), from the CVE's indicator index, whether or not the CVE is in the exploited set
        '400':
          description: '`invalid_cve_id`, `invalid_type` or `invalid_format`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`plan_required`: Pro and above'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: '`not_ready`: the indicator index has not been built yet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.ismalicious.com
      description: Production server
  /edl/exploited-cves:
    get:
      tags:
      - Blocklist
      summary: Indicators of every CVE exploited in the last 7 days
      operationId: getExploitedCvesEdl
      parameters:
      - name: type
        in: query
        description: '`ip`, `domain`, `url` or `hash` (default: all, one per line).'
        required: false
        schema:
          type: string
      - name: format
        in: query
        description: '`txt` (default, one indicator per line), `csv` (`indicator,type,cve,lastSeen`) or `json`.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 'The list (text/plain, text/csv or application/json). Enterprise: rebuilt hourly; Pro: the day''s snapshot (`X-Exploited-Snapshot`)'
        '400':
          description: '`invalid_type` or `invalid_format`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '`plan_required`: Pro and above'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: '`not_ready`: the list has not been built yet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.ismalicious.com
      description: Production server
components:
  schemas:
    BlocklistLastRun:
      type: object
      description: 'The last run of the blocklist generation job

        (`jobs:last-run:generate-blocklists`).'
      required:
      - startedAt
      - status
      properties:
        completedAt:
          type:
          - string
          - 'null'
          description: '`null` while the run is in flight'
          example: '2026-11-08T03:41:19Z'
        initiator:
          type:
          - string
          - 'null'
          description: 'Who started it: `interval-scheduler` (the worker''s ticker),

            `blocklist-api` (`POST /blocklist`), …; `null` when not recorded'
          example: interval-scheduler
        startedAt:
          type: string
          example: '2026-11-08T03:12:04Z'
        status:
          type: string
          description: '`running` | `success` | `failed` | `timeout` | `interrupted`'
          example: success
    ErrorResponse:
      type: object
      description: Error response. Some handlers return only `error`.
      required:
      - error
      properties:
        error:
          type: string
          description: Error type
          example: Bad Request
        message:
          type:
          - string
          - 'null'
          description: Detailed error message (not always present)
          example: 'Missing required parameter: query'
    BlocklistSchedule:
      type: object
      description: When the blocklists are regenerated (`api/blocklist.rs::schedule_body`).
      required:
      - intervalHours
      - schedulerEnabled
      - overdue
      properties:
        expectedNextRunAt:
          type:
          - string
          - 'null'
          description: 'When the next run is expected; `null` when it cannot be known (the

            scheduler is off, a run is in flight or was cut short, or the last run

            was started by hand and the worker has not published its next tick)'
          example: '2026-11-08T15:12:04Z'
        expectedNextRunBasis:
          type:
          - string
          - 'null'
          description: 'Where `expectedNextRunAt` comes from: `armedTick` (the tick the

            worker''s scheduler armed) or `lastScheduledRun` (computed from the

            last run the scheduler started); `null` with no date'
          example: armedTick
        intervalHours:
          type: integer
          format: int64
          description: 'Hours between two runs of the generation job

            (`BLOCKLIST_SCHEDULER_INTERVAL_HOURS`)'
          example: 12
          minimum: 0
        lastRegeneratedAt:
          type:
          - string
          - 'null'
          description: 'The newest `lastUpdated` among the lists; `null` when none was ever

            generated'
          example: '2026-11-08T03:41:19Z'
        lastRun:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/BlocklistLastRun'
            description: '`null` with no run history'
        overdue:
          type: boolean
          description: More than an hour past `expectedNextRunAt`
        schedulerEnabled:
          type: boolean
          description: Whether the scheduler is on (`BLOCKLIST_SCHEDULER_ENABLED`)
    BlocklistStat:
      type: object
      description: 'Per-file blocklist statistics entry

        (`domain/blocklist.rs::BlocklistStatEntry`)'
      required:
      - count
      - cache_ready
      properties:
        cache_ready:
          type: boolean
          description: Whether the generated file is present in cache and downloadable
        count:
          type: integer
          format: int64
          description: Number of entries in the blocklist
          minimum: 0
        last_updated:
          type:
          - string
          - 'null'
          description: Last generation timestamp (RFC 3339); absent when never generated
          example: '2026-08-28T07:00:00+00:00'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Base64 encoded `apiKey:apiSecret`. Get your keys from https://ismalicious.com/app/account
    BasicAuth:
      type: http
      scheme: basic
      description: 'Username = apiKey, password = apiSecret. Legacy: any username, password = Base64(apiKey:apiSecret).'
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <token>` where token = Base64(apiKey:apiSecret) — the same credential as X-API-KEY.'
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Secure-authjs.session-token
      description: Authenticated browser session. The claim endpoint also requires a verified email in the database; organization API keys cannot claim watches.
x-refined-from:
- ismalicious-com-openapi.json
- ismalicious-com-openapi2.json