openapi: 3.0.3
info:
  title: AbuseIPDB APIv2
  description: |
    AbuseIPDB APIv2 is a REST API for querying IP reputation, downloading the
    community blacklist, submitting single and bulk abuse reports, checking
    CIDR network ranges, and clearing your own past reports. All requests are
    authenticated with an API key supplied via the `Key` HTTP header and must
    be made over HTTPS. Responses are returned as JSON unless otherwise noted.
  version: 2.0.0
  contact:
    name: AbuseIPDB Support
    url: https://www.abuseipdb.com/contact
  license:
    name: AbuseIPDB Terms of Service
    url: https://www.abuseipdb.com/terms-of-service
  termsOfService: https://www.abuseipdb.com/terms-of-service
externalDocs:
  description: Full AbuseIPDB APIv2 Documentation
  url: https://docs.abuseipdb.com/
servers:
  - url: https://api.abuseipdb.com/api/v2
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Reputation
    description: Endpoints for looking up the abuse data of an IP or CIDR network.
  - name: Reports
    description: Endpoints for submitting and retrieving abuse reports.
  - name: Blacklist
    description: Endpoints for downloading the community blacklist.
  - name: Management
    description: Endpoints for managing your own reports.
paths:
  /check:
    get:
      operationId: checkIp
      tags:
        - Reputation
      summary: Check an IP Address
      description: |
        Returns the current abuse data for a single IPv4 or IPv6 address,
        including the abuse confidence score, country, ISP, usage type, and
        (when `verbose` is set) the most recent reports.
      parameters:
        - name: ipAddress
          in: query
          required: true
          description: The IPv4 or IPv6 address to check.
          schema:
            type: string
            format: ip
        - name: maxAgeInDays
          in: query
          description: Restrict reports considered to those within the last N days (1-365, default 30).
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
        - name: verbose
          in: query
          description: When present, include the most recent reports in the response.
          schema:
            type: boolean
      responses:
        '200':
          description: Abuse data for the requested IP.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /reports:
    get:
      operationId: listReports
      tags:
        - Reports
      summary: List Reports for an IP Address
      description: Returns a paginated list of recent reports for a given IP address.
      parameters:
        - name: ipAddress
          in: query
          required: true
          description: The IPv4 or IPv6 address whose reports should be returned.
          schema:
            type: string
            format: ip
        - name: maxAgeInDays
          in: query
          description: Restrict to reports within the last N days (1-365, default 30).
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
        - name: page
          in: query
          description: Page number to return (1-based).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          description: Number of reports per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: A page of reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /blacklist:
    get:
      operationId: getBlacklist
      tags:
        - Blacklist
      summary: Download the AbuseIPDB Blacklist
      description: |
        Returns the AbuseIPDB blacklist. Free accounts receive up to 10,000
        entries; subscriber tiers can customise the confidence floor, country
        filters, IP version, and maximum result count.
      parameters:
        - name: confidenceMinimum
          in: query
          description: Minimum confidence score (25-100, default 100; subscriber feature below 100).
          schema:
            type: integer
            minimum: 25
            maximum: 100
            default: 100
        - name: limit
          in: query
          description: Maximum number of entries to return (varies by plan, up to 500,000).
          schema:
            type: integer
            minimum: 1
            maximum: 500000
        - name: onlyCountries
          in: query
          description: Comma-separated ISO 3166-1 alpha-2 country codes to include (subscriber feature).
          schema:
            type: string
        - name: exceptCountries
          in: query
          description: Comma-separated ISO 3166-1 alpha-2 country codes to exclude (subscriber feature).
          schema:
            type: string
        - name: ipVersion
          in: query
          description: Restrict to a specific IP version (4 or 6).
          schema:
            type: integer
            enum: [4, 6]
        - name: plaintext
          in: query
          description: When present, return one IP per line as text/plain instead of JSON.
          schema:
            type: boolean
      responses:
        '200':
          description: A blacklist response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlacklistResponse'
            text/plain:
              schema:
                type: string
                description: One IP address per line.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /report:
    post:
      operationId: reportIp
      tags:
        - Reports
      summary: Report an Abusive IP Address
      description: |
        Submit a new abuse report for an IP address with one or more category
        IDs, an optional comment, and an optional ISO 8601 timestamp.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '200':
          description: The report was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /bulk-report:
    post:
      operationId: bulkReportIps
      tags:
        - Reports
      summary: Bulk Report Abusive IP Addresses
      description: Submit many abuse reports at once via a CSV multipart upload.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [csv]
              properties:
                csv:
                  type: string
                  format: binary
                  description: |
                    CSV file with columns: IP, Categories, ReportDate, Comment.
      responses:
        '200':
          description: Bulk report accepted; summary of saved/invalid entries returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkReportResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /check-block:
    get:
      operationId: checkBlock
      tags:
        - Reputation
      summary: Check a CIDR Network Block
      description: |
        Returns the abuse data for a CIDR network range. Free accounts may query
        ranges up to /24; subscriber tiers can query up to /16.
      parameters:
        - name: network
          in: query
          required: true
          description: A CIDR network range (e.g. `192.0.2.0/24`).
          schema:
            type: string
        - name: maxAgeInDays
          in: query
          description: Restrict to reports within the last N days (1-365, default 30).
          schema:
            type: integer
            minimum: 1
            maximum: 365
            default: 30
      responses:
        '200':
          description: Abuse data for the network range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckBlockResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
  /clear-address:
    delete:
      operationId: clearAddress
      tags:
        - Management
      summary: Clear Your Reports for an IP Address
      description: Remove all of your own past reports for the given IP address.
      parameters:
        - name: ipAddress
          in: query
          required: true
          description: The IPv4 or IPv6 address whose reports (filed by your account) should be cleared.
          schema:
            type: string
            format: ip
      responses:
        '200':
          description: Reports cleared successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearAddressResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Key
      description: AbuseIPDB API key. Issue and rotate at https://www.abuseipdb.com/account/api.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Validation error in the request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Daily rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds until the next allowed request.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Daily limit for this endpoint.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the current window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Epoch timestamp when the window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CheckResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/IpRecord'
    IpRecord:
      type: object
      properties:
        ipAddress:
          type: string
        isPublic:
          type: boolean
        ipVersion:
          type: integer
          enum: [4, 6]
        isWhitelisted:
          type: boolean
          nullable: true
        abuseConfidenceScore:
          type: integer
          minimum: 0
          maximum: 100
        countryCode:
          type: string
          nullable: true
        countryName:
          type: string
          nullable: true
        usageType:
          type: string
          nullable: true
        isp:
          type: string
          nullable: true
        domain:
          type: string
          nullable: true
        hostnames:
          type: array
          items:
            type: string
        isTor:
          type: boolean
        totalReports:
          type: integer
        numDistinctUsers:
          type: integer
        lastReportedAt:
          type: string
          format: date-time
          nullable: true
        reports:
          type: array
          description: Present only when `verbose` is true.
          items:
            $ref: '#/components/schemas/Report'
    Report:
      type: object
      properties:
        reportedAt:
          type: string
          format: date-time
        comment:
          type: string
        categories:
          type: array
          items:
            type: integer
        reporterId:
          type: integer
        reporterCountryCode:
          type: string
        reporterCountryName:
          type: string
    ReportsResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            total:
              type: integer
            page:
              type: integer
            count:
              type: integer
            perPage:
              type: integer
            lastPage:
              type: integer
            nextPageUrl:
              type: string
              nullable: true
            previousPageUrl:
              type: string
              nullable: true
            results:
              type: array
              items:
                $ref: '#/components/schemas/Report'
    BlacklistResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            generatedAt:
              type: string
              format: date-time
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlacklistEntry'
    BlacklistEntry:
      type: object
      properties:
        ipAddress:
          type: string
        countryCode:
          type: string
          nullable: true
        abuseConfidenceScore:
          type: integer
          minimum: 0
          maximum: 100
        lastReportedAt:
          type: string
          format: date-time
    ReportRequest:
      type: object
      required: [ip, categories]
      properties:
        ip:
          type: string
          description: IPv4 or IPv6 address to report.
        categories:
          type: string
          description: Comma-separated category IDs (up to 30).
        comment:
          type: string
          description: Optional description and supporting log evidence.
        timestamp:
          type: string
          format: date-time
          description: Optional ISO 8601 timestamp when the abuse occurred.
    ReportResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            ipAddress:
              type: string
            abuseConfidenceScore:
              type: integer
    BulkReportResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            savedReports:
              type: integer
            invalidReports:
              type: array
              items:
                type: object
                properties:
                  error:
                    type: string
                  input:
                    type: string
                  rowNumber:
                    type: integer
    CheckBlockResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            networkAddress:
              type: string
            netmask:
              type: string
            minAddress:
              type: string
            maxAddress:
              type: string
            numPossibleHosts:
              type: integer
            addressSpaceDesc:
              type: string
            reportedAddress:
              type: array
              items:
                $ref: '#/components/schemas/IpRecord'
    ClearAddressResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            numReportsDeleted:
              type: integer
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              detail:
                type: string
              status:
                type: integer
              source:
                type: object
                properties:
                  parameter:
                    type: string