InternetData Database v2 API

openapi: 3.2.0
info:
  title: InternetData Database v2 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 v2
  description: 'The current database API. Authenticate with an API key carrying the

    `db.download` scope, presented any of three ways: `Authorization: Bearer

    `, `X-Api-Key: `, or `?apikey=`. They are the same key;

    the query parameter is there for curl and the browser, which is how a

    database is usually fetched.


    Access is granted by CONTRACT, one dataset family at a time: there is no

    self-service purchase and no subscription behind it. The Open databases

    are licensed to every organization from the start, a `standard` license

    to each, and are free under CC BY-SA 4.0 besides. `list` marks them

    `open`.


    A successful download answers `302` with a time-limited URL pointing

    straight at object storage. Follow the redirect (`curl -L`); the link

    authorizes the START of a transfer, so a download already running is not

    interrupted when it lapses.'
  x-displayName: Database v2
paths:
  /api/v2/database/list:
    get:
      tags:
      - Database v2
      operationId: listDatabases
      summary: List
      description: 'The whole published catalog, with your organization''s license beside

        each entry, so `standing` says whether a database is yours today

        (`licensed`), was (`expired`), or has never been bought (`unlicensed`).'
      security:
      - ApiKeyQueryAuth: []
      - ApiKeyHeaderAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - databases
                properties:
                  databases:
                    type: array
                    items:
                      $ref: '#/components/schemas/Database'
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2IpNotAllowed'
  /api/v2/database/download:
    get:
      tags:
      - Database v2
      operationId: downloadDatabaseV2
      summary: Download
      description: 'Answers `302`; the bytes come straight from object storage rather than

        through this API. Follow the redirect.'
      security:
      - ApiKeyQueryAuth: []
      - ApiKeyHeaderAuth: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/DbId'
      - $ref: '#/components/parameters/DbFormat'
      - $ref: '#/components/parameters/DbBuild'
      responses:
        '302':
          description: Follow the Location header to object storage.
          headers:
            Location:
              schema:
                type: string
        '400':
          description: 'The database is not built in the requested format (`INVALID_FORMAT`),

            or `build` is not a build''s name (`INVALID_BUILD`).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2Forbidden'
        '404':
          $ref: '#/components/responses/V2UnknownDatabase'
        '410':
          description: 'The build named in `build` is no longer kept (`BUILD_GONE`): builds are

            kept 7 days. Download without `build` for the live one.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/V2NotAvailable'
  /api/v2/database/metadata:
    get:
      tags:
      - Database v2
      operationId: databaseMetadataV2
      summary: Metadata
      description: 'Poll this to decide whether today''s build is worth fetching: it carries

        `updated` and `entries` without downloading anything.


        No `format` parameter - one document describes every format the database

        is built in. Needs no license: it answers for every database `list`

        returns, whatever its `standing`.'
      security:
      - ApiKeyQueryAuth: []
      - ApiKeyHeaderAuth: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/DbId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatabaseMetadata'
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2IpNotAllowed'
        '404':
          $ref: '#/components/responses/V2UnknownDatabase'
        '503':
          $ref: '#/components/responses/V2NotAvailable'
  /api/v2/database/checksum:
    get:
      tags:
      - Database v2
      operationId: databaseChecksumV2
      summary: Checksums
      description: Checksums for one published file, so a download can be verified after it lands.
      security:
      - ApiKeyQueryAuth: []
      - ApiKeyHeaderAuth: []
      - BearerAuth: []
      parameters:
      - $ref: '#/components/parameters/DbId'
      - $ref: '#/components/parameters/DbFormat'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - format
                - checksums
                properties:
                  id:
                    type: string
                  format:
                    $ref: '#/components/schemas/DatabaseFormat'
                  checksums:
                    $ref: '#/components/schemas/DbChecksums'
        '400':
          description: The database is not built in the requested format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2Forbidden'
        '404':
          $ref: '#/components/responses/V2UnknownDatabase'
        '503':
          $ref: '#/components/responses/V2NotAvailable'
  /api/v2/database/downloads:
    get:
      tags:
      - Database v2
      operationId: listDownloads
      summary: History
      description: 'Refusals are listed too: a denial is what answers "it stopped working",

        and its absence answers nothing.'
      security:
      - ApiKeyQueryAuth: []
      - ApiKeyHeaderAuth: []
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        required: false
        description: How many attempts to return. Clamped to 200.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - downloads
                properties:
                  downloads:
                    type: array
                    items:
                      $ref: '#/components/schemas/Download'
        '401':
          $ref: '#/components/responses/V2Unauthorized'
        '403':
          $ref: '#/components/responses/V2IpNotAllowed'
components:
  responses:
    V2UnknownDatabase:
      description: 'No such database.

        `rc`: `UNKNOWN_DATASET`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    V2Forbidden:
      description: 'Your organization holds no license for this database (`NOT_LICENSED`),

        or its term has ended (`LICENSE_EXPIRED`); or the request comes from an

        address outside the key''s or its organization''s allowed addresses

        (`IP_NOT_ALLOWED`).

        `rc`: `NOT_LICENSED`, `LICENSE_EXPIRED`, `IP_NOT_ALLOWED`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    V2NotAvailable:
      description: 'The current build has not been published yet.

        `rc`: `NOT_AVAILABLE`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    V2IpNotAllowed:
      description: 'The request comes from an address outside the key''s or its

        organization''s allowed addresses. Change the allowlist or call from an

        allowed address: the key itself is fine.

        `rc`: `IP_NOT_ALLOWED`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    V2Unauthorized:
      description: 'Missing, invalid, revoked or expired key; the key lacks the

        `db.download` scope; or the key belongs to no active organization.

        Each answers the same.

        `rc`: `UNAUTHORIZED`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    DatabaseMetadataColumn:
      type: object
      required:
      - name
      - type
      properties:
        name:
          type: string
        type:
          type: string
        description:
          type: string
    DatabaseFormat:
      type: string
      description: A file format a database version is published in.
      enum:
      - csvgz
      - mmdb
      example: mmdb
    DatabaseVersion:
      type: object
      required:
      - id
      - version
      - summary
      - formats
      properties:
        id:
          type: string
          description: The versioned ID. Pass this to `download`, `checksum` and `metadata`.
          example: vpn_ip_v1
        version:
          type: integer
          example: 1
        summary:
          type: string
        formats:
          type: array
          description: 'The formats this version is BUILT in. Asking for another is a 400,

            not a gap - the `_provider` catalogs are keyed by provider ID, so no

            MMDB exists for them.

            '
          items:
            $ref: '#/components/schemas/DatabaseFormat'
        sample_formats:
          type: array
          description: The formats an evaluation sample is published in, if any.
          items:
            $ref: '#/components/schemas/DatabaseFormat'
    Standing:
      type: string
      description: 'Where your license for a database family stands today. `licensed` is a

        live grant, `expired` one whose term has ended, and `unlicensed` a

        database published but never bought.

        '
      enum:
      - licensed
      - expired
      - unlicensed
    Database:
      type: object
      description: 'One database FAMILY, with your organization''s license beside it. A

        license covers the family, while a download names a specific version,

        so the IDs passed to `download` and `checksum` come from `versions`.

        '
      required:
      - base
      - name
      - summary
      - standing
      - open
      - license_type
      - starts
      - expires
      - renews_at
      - notice_due_at
      - versions
      properties:
        base:
          type: string
          description: The family, e.g. `vpn_ip`. What a license is held against.
          example: vpn_ip
        name:
          type: string
          example: VPN IP
        summary:
          type: string
          description: One line on what the newest version contains.
        standing:
          $ref: '#/components/schemas/Standing'
        open:
          type: boolean
          description: 'An Open database: free under CC BY-SA 4.0 (credit InternetData,

            https://internetdata.io, and share what you build from it under

            the same license). Every organization holds a `standard` license

            to it from the start, which `standing` and `license_type` report

            like any other.

            '
        license_type:
          type:
          - string
          - 'null'
          enum:
          - evaluation
          - standard
          - redistribute
          - null
          description: 'What your license permits you to do with the data. Null when there

            is no license, which is every family with standing `unlicensed`.

            '
        starts:
          type:
          - string
          - 'null'
          format: date-time
        expires:
          type:
          - string
          - 'null'
          format: date-time
          description: A hard stop. Null when the license has no end date, which is the normal case for a rolling agreement, and when there is no license. A rolling license reports its turnover date in renews_at instead.
        renews_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When a rolling license next renews. Null when the license has no defined term, when expires sets a hard stop instead, and when there is no license.
        notice_due_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The last day notice of non-renewal can be given for the term ending at renews_at. Null whenever renews_at is, and when the agreement records no notice period.
        versions:
          type: array
          description: 'Every published version of this family, oldest first. Old versions

            are frozen rather than migrated, so both stay downloadable.

            '
          items:
            $ref: '#/components/schemas/DatabaseVersion'
    Download:
      type: object
      description: One download ATTEMPT, refusals included.
      required:
      - dataset_id
      - format
      - outcome
      - sample
      - open
      - bytes
      - http_status
      - apikey_id
      - client_ip
      - user_agent
      - created
      properties:
        dataset_id:
          type: string
        format:
          type: string
        outcome:
          type: string
          enum:
          - ok
          - unauthorized
          - denied
          - expired
          - unknown
          - unavailable
        sample:
          type: boolean
          description: The evaluation sample rather than the database itself.
        open:
          type: boolean
          description: 'A download of an Open database.

            '
        bytes:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Object size at redirect time, NOT bytes delivered: the transfer is a

            presigned redirect straight to object storage, so we never observe

            how much of it was taken.

            '
        http_status:
          type:
          - integer
          - 'null'
        apikey_id:
          type:
          - string
          - 'null'
          description: The key that made the request. Null when it could not be resolved.
        client_ip:
          type:
          - string
          - 'null'
        user_agent:
          type:
          - string
          - 'null'
        created:
          type: string
          format: date-time
    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.
    DatabaseMetadata:
      type: object
      description: The build document written by the exporter, served through unchanged.
      required:
      - id
      - updated
      - entries
      - schema
      - size
      properties:
        id:
          type: string
        update_freq:
          type: string
          description: How often a new build is published.
        updated:
          type: string
          format: date
          description: ISO-8601 date (YYYY-MM-DD) the published build was generated on.
          example: '2026-09-04'
        entries:
          type: integer
          format: int64
          description: Row count in the current build.
        schema:
          type: object
          description: Columns, keyed by format.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/DatabaseMetadataColumn'
        sample:
          type: object
          description: A few real rows, keyed by format.
          additionalProperties:
            type: array
            items:
              type: object
        size:
          type: object
          description: Bytes per format.
          additionalProperties:
            type: integer
            format: int64
        sample_size:
          type: object
          description: Bytes per format of the evaluation sample, where one is published.
          additionalProperties:
            type: integer
            format: int64
        sample_entries:
          type: integer
          description: Row count in the evaluation sample.
    Error:
      type: object
      required:
      - rc
      properties:
        rc:
          type: string
          description: 'A machine-readable result code. Deliberately not an enum: a code

            added later must stay parseable by a client generated today.

            '
  parameters:
    DbBuild:
      name: build
      in: query
      required: false
      description: 'One build of the database, by the name a `database.updated` webhook gives

        it, so the file is the one whose `sha256` the webhook carries. Without

        it, the build that is live.

        '
      schema:
        type: string
        pattern: ^[0-9]{8}\.[a-z0-9]{6}$
        example: 20261105.0t53s5
    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