Hubble Network Packets API

openapi: 3.2.0
info:
  title: Hubble Platform Packets API
  description: The Hubble platform is built API-first.
  version: 1.0.0
servers:
- url: https://api.hubble.com
  description: Production
security:
- BearerAuth: []
tags:
- name: Packets
paths:
  /v1/org/{org_id}/packets:
    get:
      tags:
      - Packets
      operationId: retrieve-organization-packets
      x-criticality: high
      summary: Retrieve Organization Packets
      description: 'Stream or query packets for your organization.


        **Required Scope:** `read-packets`


        ## Overview

        This endpoint acts as a data stream. Use the `Continuation-Token` to track your consumer''s position in the stream and ingest incrementally.

        Packets are returned in ascending order based on when they were detected by Hubble Network.


        ## Pagination and Streaming

        Use the `Continuation-Token` to capture new packets incrementally.

        If provided, all other query parameters are ignored, as the token persists the initial query''s configuration.


        ### Response Headers

        * `Continuation-Token`: provided if more packets are available. The max page size is 1,000 packets. An empty string indicates there are no new packets in the stream.

        * `Retry-After`: if the stream is empty, this integer provides the recommended number of seconds to wait before your next poll request (max value is 300 seconds).


        ## Query Parameters (Initial Request)

        When starting a new stream (no `Continuation-Token` exists) or to query for data from a period of time, use these parameters to begin polling:


        ### Time Period (UTC, in seconds)

        * `start` time defaults to 7 days ago when not specified.

        * Omit `end` time to leave the stream open and poll for new packets as they become available.


        :::tip

        Granular packet data is available up to **30 days** in the past.

        :::


        ### Device Filtering

        * When `device_id` is provided, only packets from that device will be returned.

        * Note: you cannot page indefinitely for single-device queries. The stream closes when it reaches current time.


        :::warning

        Device filtering is provided for troubleshooting. It should not be used for high-volume data retrieval.

        :::


        ### Tag Filtering

        * You may filter packet data by device **platform tags**: `_env:production`, `_env:sandbox`.

        * **Custom tags are not currently supported.**


        ---


        ## Packet Data Definitions (Response)


        ### Location Object

        For **TERRESTRIAL** packets, all `location` fields represent the scanning gateway''s most recent GPS lock:

        * `location.timestamp` is the timestamp of the location lock.

        * `location.latitude` and `location.longitude` are the location coordinates.

        * `location.horizontal_accuracy` and `location.vertical_accuracy` represent accuracy variance in meters.


        For **SATELLITE** packets, `location.timestamp` and `device.timestamp` are identical: both represent the time the packet was detected by the satellite.


        ### Device Object

        For **TERRESTRIAL** packets,

        * `device.timestamp` is the timestamp when the data packet was detected by the gateway.

        * `device.rssi` is the received signal strength measured by the gateway.


        ### Gateway Object

        For **self-provided** packets (packets your organization contributed and is also reading back, i.e. `provider_id == org_id`), the response optionally includes a top-level `gateway` object. These fields describe the **scanning gateway** that received the BLE advertisement.

        * `gateway.gateway_id` is the stable gateway UUID issued by Hubble when you register using the Gateway API.

        * `gateway.service_id` is the normalized 16-bit service UUID from the scanned BLE advertisement (e.g. `fca6`).


        :::note

        The `gateway` block is **omitted entirely** for packets sourced from a different organization (e.g. third-party crowdsourced traffic), and is also omitted on self-provided packets when no gateway context was attached at ingest.

        :::'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - $ref: '#/components/parameters/continuationTokenHeader'
      - $ref: '#/components/parameters/startQueryParam'
      - $ref: '#/components/parameters/endQueryParam'
      - $ref: '#/components/parameters/deviceIdQueryParam'
      - $ref: '#/components/parameters/filterTagsQueryParam'
      responses:
        '200':
          description: A page of packets
          headers:
            Continuation-Token:
              $ref: '#/components/headers/ContinuationTokenHeader'
            Retry-After:
              $ref: '#/components/headers/RetryAfterHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/packetBatch'
        '429':
          description: An error when too many requests have been made to retrieve packets
          headers:
            Continuation-Token:
              $ref: '#/components/headers/ContinuationTokenHeader'
            Retry-After:
              $ref: '#/components/headers/RetryAfterHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/webhook/testBatch:
    post:
      tags:
      - Packets
      operationId: packet-webhook-example
      x-criticality: high
      summary: Packet Webhook Example
      description: 'This endpoint is an example webhook endpoint that each organization can implement in order to receive packet data.

        Packet data that has been decrypted for your organization will be forwarded to these webhooks.


        ### Batching

        Packets are sent in batches to minimize HTTP overhead from sending packets individually.

        Batch sizes are configurable per webhook endpoint.

        The actual number of packets per request will range between 1 and the configured `max_batch_size`.'
      parameters:
      - $ref: '#/components/parameters/contentTypeJsonHeader'
      - $ref: '#/components/parameters/webhookSecretHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/packetBatch'
      responses:
        '200':
          description: Message delivered.
        '500':
          description: Internal Server Error. Please Retry.
components:
  schemas:
    deviceId:
      type: string
      format: uuid
      description: Primary UUID identifier for a registered device
    gateway:
      type: object
      description: 'Metadata about the scanning gateway that received this packet — the relay

        that detected the BLE advertisement, not the device that emitted it.

        Only present on self-provided packets (`provider_id == org_id`) where

        gateway context was attached at ingest. Both fields are optional.

        '
      properties:
        gateway_id:
          type: string
          format: uuid
          description: 'Stable unique identifier of the gateway device that received the packet.

            This is the gateway UUID issued at registration time and is consistent

            across all packets from the same gateway.

            '
        service_id:
          type: string
          description: 'Normalized 16-bit BLE service UUID that the advertisement was scanned

            under (lowercase hex, e.g. `fca6` for Hubble packets). Identifies which

            BLE service profile the gateway matched when it captured this packet.

            '
          example: fca6
    packet:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/location'
        device:
          type: object
          required:
          - id
          - payload
          - timestamp
          properties:
            id:
              $ref: '#/components/schemas/deviceId'
            name:
              $ref: '#/components/schemas/deviceName'
            tags:
              $ref: '#/components/schemas/deviceTags'
            payload:
              type: string
              description: A packet's decrypted payload in Base64 format
            rssi:
              type: number
            timestamp:
              $ref: '#/components/schemas/utcTimestampNumber'
            counter:
              type: number
              description: 'The time-based counter associated with this packet.

                '
            sequence_number:
              type: number
              description: 'The sequence number of this packet

                '
        network_type:
          type: string
          enum:
          - TERRESTRIAL
          - SATELLITE
        gateway:
          $ref: '#/components/schemas/gateway'
    location:
      type: object
      required:
      - latitude
      - longitude
      - altitude
      - timestamp
      properties:
        latitude:
          type: number
          description: Latitude in Decimal Degrees DDD.DDDDD°
        longitude:
          type: number
          description: Longitude in Decimal Degrees DDD.DDDDD°
        altitude:
          type: number
          description: Altitude in meters for the provided gps coordinates
        horizontal_accuracy:
          type: number
          description: Horizontal accuracy in meters for the provided gps coordinates
        vertical_accuracy:
          type: number
          description: Vertical accuracy in meters for the provided gps coordinates
        timestamp:
          $ref: '#/components/schemas/utcTimestampNumber'
    errorResponse:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP status code
        description:
          type: string
          description: 'A description for the error.

            For user errors, we attempt to be as descriptive as possible to help with diagnosing the issue.

            For internal errors, the error description is only indicates that a retry should occur but we log the full error so that we can diagnose it.

            Error descriptions can change over time and should not be programmed against.

            '
        name:
          type: string
          enum:
          - Bad Request
          - Unauthorized
          - Not Found
          - Too Many Requests
          - Internal Server Error
          description: '`name` is a short name for the error.

            '
    packetBatch:
      type: object
      properties:
        packets:
          type: array
          items:
            $ref: '#/components/schemas/packet'
    utcTimestampInteger:
      type: integer
      format: int64
      description: An UTC second-precision timestamp formatted as an integer
    deviceTags:
      type: object
      additionalProperties:
        type: string
      description: "Tags are user-defined key/value pairs that can be attributed to a device. \nA device may have up to 10 tags.\n**Custom tags:** create your own tags with `key` length up to 32 characters and `value` length up to 128 characters.\n**Platform tags:** use Hubble-defined tags to organize devices.\n- `_env` tag: `production` indicates if a device belongs to the live environment, and `sandbox` for the test environment. A device will always have an `_env` tag assigned.\n"
      example:
        _env: production
    utcTimestampNumber:
      type: number
      format: double
      description: An UTC second-precision timestamp formatted as a floating point number
    orgId:
      type: string
      format: uuid
      description: The ID for an organization
    webhookSecret:
      type: string
      description: 'A confidential, unique string generated for your webhook endpoint to validate that the request came from Hubble.

        Hubble will send this token in the HTTP header `HTTP-X-HUBBLE-TOKEN` when making HTTPS requests to your endpoint.

        '
    deviceName:
      type: string
      description: Assigned name for the device
      maxLength: 250
  responses:
    ErrorBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 400
            description: The request could not be understood by the server due to malformed syntax.
            name: Bad Request
    ErrorInternalServer:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 500
            description: An unknown error has occurred.
            name: Unknown
  parameters:
    webhookSecretHeader:
      name: HTTP-X-HUBBLE-TOKEN
      in: header
      required: true
      schema:
        $ref: '#/components/schemas/webhookSecret'
      description: 'A confidential, unique string generated for your webhook endpoint to validate that the request came from Hubble.

        '
    contentTypeJsonHeader:
      name: Content-Type
      in: header
      schema:
        type: string
      description: An indication that the payload is JSON
      example: application/json
    endQueryParam:
      name: end
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/utcTimestampInteger'
      description: 'UTC timestamp (in seconds) indicating when to end retrieving packets.

        This timestamp corresponds to when the packet was received by the network.

        If omitted, defaults to empty (meaning the pagination will continue indefinitely).

        If specified, pagination will continue until all packets received prior to the timestamp have been returned.

        '
    startQueryParam:
      name: start
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/utcTimestampInteger'
      description: "UTC timestamp (in seconds) indicating when to start retrieving packets. \nThis timestamp corresponds to when the packet was received by the network.\nIf omitted, defaults to 7 days before the current UTC time.\n"
    continuationTokenHeader:
      name: Continuation-Token
      in: header
      required: false
      schema:
        type: string
      description: A token to indicate how to continue paging
    deviceIdQueryParam:
      name: device_id
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/deviceId'
      description: 'Filter packets to a specific device

        '
    filterTagsQueryParam:
      name: filter_tags
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          description: 'A tag to match against. For example: _env:production.

            '
      description: 'A set of device **platform tags** specifying which packets to include.

        Only platform tags are queryable: `_env:production`, `_env:sandbox`.

        The query param can be used multiple times to form a list of tags.

        Packet matching criteria uses AND logic when different tag keys are used in a list of tags, and OR logic when the same tag key is used more than once.

        '
    orgIdPathParam:
      name: org_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/orgId'
      description: Your organization ID
  headers:
    RetryAfterHeader:
      description: 'The number of seconds to wait to attempt a retry.

        When attached to a 200, this is a suggestion because the most recent data has been retrieved already.

        When attached to a 429, this delay is a recommendation to reduce repeat 429s.

        '
      schema:
        type: integer
        minimum: 0
        maximum: 300
    ContinuationTokenHeader:
      description: A token to indicate how to continue paging
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT