InternetData Database API

openapi: 3.2.0
info:
  title: InternetData Database API
  description: 'The InternetData API: download the databases your organization is licensed

    for, and manage the account behind them.


    See https://docs.internetdata.io for guides and https://github.com/internetdata

    for the official client libraries.'
  contact:
    name: InternetData Support
    email: support@internetdata.io
    url: https://internetdata.io
  termsOfService: https://internetdata.io/terms
  version: 2026.11.08
servers:
- url: https://internetdata.io
tags:
- name: Database
  description: Download IP database files and fetch their checksums.
  x-displayName: Database
paths:
  /api/v1/database/download:
    get:
      tags:
      - Database
      operationId: databaseDownload
      summary: Download
      description: 'Returns the requested database file as a binary download.

        The response''s `Content-Type` depends on `format`:

        `application/gzip` for `csvgz`, `application/octet-stream` for `mmdb`.'
      parameters:
      - $ref: '#/components/parameters/DbId'
      - $ref: '#/components/parameters/DbFormat'
      responses:
        '200':
          description: Database file.
          headers:
            Content-Disposition:
              description: Attachment with the database filename.
              schema:
                type: string
          content:
            application/gzip:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - ApiKeyAuth: []
  /api/v1/database/checksum:
    get:
      tags:
      - Database
      operationId: databaseChecksum
      summary: Checksums
      description: 'Returns MD5, SHA-1, SHA-256, and SHA-512 checksums for the currently

        published version of the requested database.'
      parameters:
      - $ref: '#/components/parameters/DbId'
      - $ref: '#/components/parameters/DbFormat'
      responses:
        '200':
          description: Checksums for the requested database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DbChecksumSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - ApiKeyAuth: []
  /api/v1/database/metadata:
    get:
      tags:
      - Database
      operationId: databaseMetadata
      summary: Metadata
      description: 'Returns publish freshness information for the currently published version

        of the requested database: when it was last updated, how many entries

        the dataset contains, and the size of each output format in bytes.'
      parameters:
      - $ref: '#/components/parameters/DbId'
      responses:
        '200':
          description: Metadata for the requested database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DbMetadataSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    DbChecksumSuccessResponse:
      type: object
      required:
      - rc
      - data
      properties:
        rc:
          type: string
          enum:
          - SUCCESS
        data:
          $ref: '#/components/schemas/DbChecksums'
    DbInvalidIdError:
      type: object
      required:
      - rc
      properties:
        rc:
          type: string
          enum:
          - INVALID_ID
    DatabaseFormat:
      type: string
      description: A file format a database version is published in.
      enum:
      - csvgz
      - mmdb
      example: mmdb
    DbMetadata:
      type: object
      required:
      - updated
      - entries
      - size
      properties:
        updated:
          type: string
          format: date
          description: ISO-8601 calendar date (YYYY-MM-DD) on which the currently published version was generated.
          example: '2026-04-25'
        entries:
          type: integer
          format: int64
          minimum: 0
          description: Number of data rows in the published dataset (excluding the CSV header).
          example: 114000000
        size:
          type: object
          required:
          - csvgz
          description: Sizes in bytes of the published files, keyed by format.
          properties:
            csvgz:
              type: integer
              format: int64
              minimum: 0
              description: Size of the gzipped CSV file in bytes.
            mmdb:
              type: integer
              format: int64
              minimum: 0
              description: Size of the MMDB file in bytes (omitted when the dataset has no MMDB output).
    DbUnauthorizedIdError:
      type: object
      required:
      - rc
      properties:
        rc:
          type: string
          enum:
          - UNAUTHORIZED_ID
    DbMetadataSuccessResponse:
      type: object
      required:
      - rc
      - data
      properties:
        rc:
          type: string
          enum:
          - SUCCESS
        data:
          $ref: '#/components/schemas/DbMetadata'
    DbNotFoundError:
      type: object
      required:
      - rc
      properties:
        rc:
          type: string
          enum:
          - DB_NOT_FOUND
    DbChecksums:
      type: object
      required:
      - md5
      - sha1
      - sha256
      - sha512
      properties:
        md5:
          type: string
          description: Hex-encoded MD5 digest.
        sha1:
          type: string
          description: Hex-encoded SHA-1 digest.
        sha256:
          type: string
          description: Hex-encoded SHA-256 digest.
        sha512:
          type: string
          description: Hex-encoded SHA-512 digest.
    DbInvalidApiKeyError:
      type: object
      required:
      - rc
      properties:
        rc:
          type: string
          enum:
          - INVALID_APIKEY
    DbInvalidFormatError:
      type: object
      required:
      - rc
      properties:
        rc:
          type: string
          enum:
          - INVALID_FORMAT
  responses:
    BadRequest:
      description: 'The request query parameters were malformed.

        Possible `rc` values: `INVALID_FORMAT`, `INVALID_ID`.

        '
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/DbInvalidFormatError'
            - $ref: '#/components/schemas/DbInvalidIdError'
    Unauthorized:
      description: The `apikey` query parameter was missing or not recognized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DbInvalidApiKeyError'
    NotFound:
      description: The requested database file does not exist on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DbNotFoundError'
    Forbidden:
      description: The `apikey` is valid but is not authorized for the requested database ID.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DbUnauthorizedIdError'
  parameters:
    DbFormat:
      name: format
      in: query
      required: true
      description: Database file format.
      schema:
        $ref: '#/components/schemas/DatabaseFormat'
    DbId:
      name: id
      in: query
      required: true
      description: Database identifier (e.g. `vpn_ip_v1`, `resproxy_provider_v1`).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_]+$
        example: vpn_ip_v1
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apikey
      description: 'UUID-format API key issued to the customer. Each key is authorized for a

        specific set of database IDs; requesting any other ID returns 403.


        v1 only. The v2 endpoints take a console-issued key as a bearer token.

        '
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <key>`, with a key from the console. Keys are

        default-deny: each operation names the scope it needs, and an existing

        key does not gain an operation until that scope is added to it.

        '
    ApiKeyHeaderAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: '`X-Api-Key: <key>`. The same v2 key, for clients that do not set a bearer.'
    ApiKeyQueryAuth:
      type: apiKey
      in: query
      name: apikey
      description: '`?apikey=<key>`. Convenient in a browser or a curl one-liner, which is

        how a database is usually fetched; prefer a header elsewhere.


        This is the same v2 key as the other two schemes. A v1 credential is a

        different vocabulary and fails validation here, as it would anywhere.

        '
x-tagGroups:
- name: InternetData Database API
  tags:
  - Database
  - Database v2
- name: InternetData IAM API
  tags:
  - Account
  - Organization
  - API keys
- name: InternetData Authorization
  tags:
  - Authorization