Hubble Network Billing API

openapi: 3.2.0
info:
  title: Hubble Platform Billing API
  description: 'The Hubble platform is built API-first. Use our Cloud API to manage your devices

    and access device data programmatically. We''ve designed our API following RESTful principles. Each endpoint returns standard HTTP status codes and may include JSON payloads. ---


    ## API Access

    Use API Keys to authenticate with the Hubble Cloud API for your organization. ### Generate an API Key

    Log in to your Hubble dashboard. Navigate to **Developer Tools > API Tokens** to create a new API Key. Provide a name for the token, and set an appropriate expiration date for temporary access. ### Organization ID

    You will need `org_id` to make API requests. From your Hubble dashboard, navigate to

    **Developer Tooks > API Tokens**, or **Organization Settings**, to find your Organization ID. ### Authorization Scopes

    API endpoints require specific authorization scopes to perform the intended operation. **Required Scope** is always provided in the API documentation. API Keys can be created with specific authorization scopes that control what operations the key can perform. If no scopes are specified, the key will be created with all available scopes (admin-level access). | **Scope** | **Access** |

    |------------------------------|-------------------------------------------------|

    | **read-api-keys** | View API keys and their metadata |

    | **write-api-keys** | Create, update, and delete API keys |

    | **read-users** | View user information and roles |

    | **write-users** | Add, update, and remove users from the organization |

    | **read-organization-metadata** | View organization details and settings |

    | **write-organization-metadata** | Update organization information |

    | **read-devices** | View device information and status |

    | **write-devices** | Register and manage devices |

    | **read-invitations** | View pending invitations |

    | **write-invitations** | Create and revoke user invitations |

    | **read-packets** | Access packet data and retrieval endpoints |

    | **read-platform-metrics** | View platform metrics and analytics |

    | **read-billing-usage** | View billing usage information |

    | **read-billing-invoices** | View billing invoices |

    | **read-webhooks** | View webhook configurations |

    | **write-webhooks** | Create and manage webhook endpoints |

    | **read-satellites** | View satellite ephemeris and pass data |


    **Example Scope Combinations**

    - Create a key with read-only access: `["read-api-keys", "read-users", "read-devices"]`

    - Create a key for device management: `["read-devices", "write-devices"]`

    - Create a key for user management: `["read-users", "write-users", "read-invitations", "write-invitations"]`


    **Best Practices for Data Security**

    - Create keys with the minimum required scopes for your use case

    - Regularly review and rotate API keys

    - Use descriptive names for your keys to track their purpose

    - Set appropriate expiration dates for temporary access


    ---


    ## Import API Definition

    You can quickly import the Hubble Cloud API into your preferred developer environment (such as Postman or Insomnia) using our **public OpenAPI definition**. Simply download or import the YAML file directly:


    https://hubble.com/docs/openapi.yaml


    ---


    ## Pagination

    When the number of objects requested exceeds the maximum page size for an endpoint, the API response will be paginated. This means you will receive a subset of the total results, along with a `Continuation-Token` in the Response Header that can be used to fetch subsequent subsets. To retrieve the next set of data, you must use the provided `Continuation-Token` in the Request Header of your next API call to the same endpoint. Continue using the provided token in each successive request until no `Continuation-Token` is returned, which indicates you have retrieved all available data. ---


    ## Rate Limits

    The Hubble Cloud API follows a leaky bucket approach to rate limiting. Endpoints are rate limited to three (3) requests per second. Your organization is limited to a total of 15 requests per second.'
  version: 1.0.0
servers:
- url: https://api.hubble.com
  description: Production
security:
- BearerAuth: []
tags:
- name: Billing
paths:
  /v1/org/{org_id}/billing/invoices:
    get:
      tags:
      - Billing
      operationId: get-recent-invoices
      x-criticality: medium
      summary: Get Recent Invoices
      description: 'Retrieve the most recent invoices for your organization.


        **Required Scope:** `read-billing-invoices`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        '200':
          description: A page of invoices
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      type: object
                      properties:
                        invoice_id:
                          type: string
                          description: the primary id for the invoice
                        invoice_number:
                          type: string
                          description: 'Customer-facing invoice number (e.g. Stripe `number`), matching what appears on the PDF.

                            '
                        issue_timestamp:
                          $ref: '#/components/schemas/utcTimestampNumber'
                        due_timestamp:
                          $ref: '#/components/schemas/utcTimestampNumber'
                        status:
                          type: string
                          enum:
                          - DRAFT
                          - PENDING
                          - COMPLETED
                          description: "A status for the invoice. \nThe invoice starts as a DRAFT and then transitions to PENDING when it is ready to be paid.\nA fully paid invoice is then COMPLETED.\n"
                        total_balance:
                          type: number
                          format: float
                          description: 'The total balance amount on the invoice. The value is based on the organization''s currency.

                            '
                        remaining_balance:
                          type: number
                          format: float
                          description: 'The remaining balance due on the invoice. The value is based on the organization''s currency.

                            '
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/billing/invoices/{invoice_id}/pdf:
    get:
      tags:
      - Billing
      operationId: get-invoice-pdf
      x-criticality: medium
      summary: Get Invoice PDF
      description: 'Retrieve an invoice PDF.


        **Required Scope:** `read-billing-invoices`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - name: invoice_id
        in: path
        required: true
        schema:
          type: string
        description: The primary key for an invoice
      responses:
        '200':
          description: A PDF document for an invoice
          content:
            application/pdf:
              schema:
                type: string
                format: binary
                description: the PDF contents
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/billing/usage:
    get:
      tags:
      - Billing
      operationId: get-billing-usage
      x-criticality: medium
      summary: Get Billing Usage
      description: 'Retrieve the most recent billing usage for your organization.


        **Required Scope:** `read-billing-usage`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        '200':
          description: A page of usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  usage:
                    type: array
                    items:
                      type: object
                      properties:
                        usage_timestamp:
                          $ref: '#/components/schemas/formattedTimestamp'
                        usage_type:
                          type: string
                          enum:
                          - Active Device
                          - Daily Active Devices
                          - Monthly Active Devices
                          - Daily Active Devices (Terrestrial)
                          - Daily Active Devices (Satellite)
                          - Monthly Active Devices (Terrestrial)
                          - Monthly Active Devices (Satellite)
                          - Factory Mode Registered Devices
                          description: 'The type of usage recorded. `Active Device` is the total count of

                            active devices for the billing period; `Daily`/`Monthly Active

                            Devices` report that same count on a daily or monthly cadence, split

                            further by how the device was heard — terrestrial or satellite.

                            `Factory Mode Registered Devices` counts devices registered while in

                            factory mode, independent of whether they were active.

                            '
                        usage_value:
                          type: integer
                          description: 'The usage value for this type and timestamp.

                            '
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/billing/active-devices:
    get:
      tags:
      - Billing
      operationId: get-billing-active-devices
      x-criticality: medium
      summary: List Active Devices in Billing Period
      description: 'Retrieve devices that were active during your organization''s current billing period.

        A device is considered active if its most recent packet timestamp falls within the period.


        **Required Scope:** `read-billing-usage`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - $ref: '#/components/parameters/continuationTokenHeader'
      - $ref: '#/components/parameters/limitQueryParam'
      - name: network_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - terrestrial
          - satellite
        description: 'Filter devices by network type. Omit to include all network types.

          Requesting `satellite` requires the organization to have satellite access.

          '
      responses:
        '200':
          description: Active devices for the billing period
          headers:
            Continuation-Token:
              $ref: '#/components/headers/ContinuationTokenHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingActiveDevicesResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '403':
          $ref: '#/components/responses/ErrorForbidden'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
components:
  schemas:
    orgId:
      type: string
      format: uuid
      description: The ID for an organization
    BillingActiveDevice:
      type: object
      required:
      - device_id
      - name
      properties:
        device_id:
          type: string
          description: The device identifier.
        name:
          type: string
          description: The device display name.
        network_type:
          type: string
          enum:
          - terrestrial
          - satellite
          description: The network on which the device was most recently active.
        last_active:
          type: number
          format: double
          description: Unix timestamp (seconds, fractional) of the device's most recent packet.
    formattedTimestamp:
      type: string
      format: date-time
      description: "Start of the bucket in ISO 8601 format.\nFor example: `2025-04-25T14:01:54Z`. \n"
    BillingActiveDevicesResponse:
      type: object
      required:
      - devices
      - period_start
      - period_end
      properties:
        devices:
          type: array
          items:
            $ref: '#/components/schemas/BillingActiveDevice'
        period_start:
          type: string
          format: date-time
          description: Start of the current billing period (ISO 8601).
        period_end:
          type: string
          format: date-time
          description: End of the current billing period (ISO 8601).
    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
          - Request Entity Too Large
          - Too Many Requests
          - Internal Server Error
          description: '`name` is a short name for the error.

            '
    utcTimestampNumber:
      type: number
      format: double
      description: An UTC second-precision timestamp formatted as a floating point number
  parameters:
    continuationTokenHeader:
      name: Continuation-Token
      in: header
      required: false
      schema:
        type: string
      description: A token to indicate how to continue paging
    orgIdPathParam:
      name: org_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/orgId'
      description: Your organization ID
    limitQueryParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        maximum: 1000
        minimum: 10
        default: 250
      description: A limit for the page size of devices
  responses:
    ErrorForbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 403
            description: The authenticated principal is not allowed to perform this operation.
            name: Forbidden
    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
  headers:
    ContinuationTokenHeader:
      description: A token to indicate how to continue paging
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Hubble Network
  source: https://hubble.com/docs/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)