isMalicious Stats API

openapi: 3.2.0
info:
  title: Ismalicious Com Stats 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 stats 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: Stats
  description: Public dataset statistics — no authentication, not metered
paths:
  /stats:
    get:
      tags:
      - Stats
      summary: Public dataset statistics
      description: 'Headline counters for the indicator dataset, read from the metrics

        snapshot the `load-metrics` job writes to Redis. **Always 200**: when the

        snapshot is missing or a field is absent, the counters are `0` and

        `topCategories` is empty — the only error response is the per-IP `429`

        below. `lastUpdated` is

        the snapshot''s own `computedAt` stamp (RFC 3339, written by the

        `load-metrics` job), `null` when no snapshot exists — never the response

        time, so a stale snapshot is visible as such. `topCategories` holds at

        most five entries.


        **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`. An answer can be

        up to a minute old.'
      operationId: getPublicStats
      responses:
        '200':
          description: Dataset counters
          headers:
            CDN-Cache-Control:
              schema:
                type: string
              description: Always `public, max-age=300`
            Cache-Control:
              schema:
                type: string
              description: Always `public, s-maxage=300, stale-while-revalidate=600`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicStats'
        '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
components:
  schemas:
    RecentActivity:
      type: object
      required:
      - last24h
      - last7d
      - growthRate
      properties:
        growthRate:
          type: number
          format: double
        last24h:
          type: integer
          format: int64
          description: 'IP and domain indicators added to the corpus in the last 24 hours (by

            their date of entry; a known indicator listed again is not counted).'
          minimum: 0
        last7d:
          type: integer
          format: int64
          description: Same, over the last 7 days, the last 24 hours included.
          minimum: 0
    MultiSourceValidated:
      type: object
      required:
      - count
      - percentage
      properties:
        count:
          type: integer
          format: int64
          minimum: 0
        percentage:
          type: number
          format: double
    PublicStats:
      type: object
      required:
      - totalThreats
      - byType
      - multiSourceValidated
      - recentActivity
      - topCategories
      - sourceCount
      properties:
        byType:
          $ref: '#/components/schemas/ByType'
        lastUpdated:
          type:
          - string
          - 'null'
          description: '`computedAt` of the `metrics:threats` snapshot the counters were read

            from (RFC 3339), or `null` when no snapshot exists. Never the response

            time: a counter served from a stale snapshot must say so.'
        multiSourceValidated:
          $ref: '#/components/schemas/MultiSourceValidated'
        recentActivity:
          $ref: '#/components/schemas/RecentActivity'
        sourceCount:
          type: integer
          format: int64
          minimum: 0
        topCategories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        totalThreats:
          type: integer
          format: int64
          minimum: 0
    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'
    ByType:
      type: object
      required:
      - domains
      - ips
      properties:
        domains:
          type: integer
          format: int64
          minimum: 0
        ips:
          type: integer
          format: int64
          minimum: 0
    Category:
      type: object
      required:
      - name
      - count
      - percentage
      properties:
        count:
          type: integer
          format: int64
          minimum: 0
        name:
          type: string
        percentage:
          type: number
          format: double
  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