canonical: https://jentic.com/apis/hubble.com/hubble

# Hubble Platform API

The Hubble Platform API manages an organization's devices on the Hubble network and the packet data they send. It registers new devices with their encryption settings in batches of up to 1,000, updates names, tags, and install locations, retrieves packets by time range or device_id, and decodes raw advertisements. Webhook endpoints receive decrypted packets in batches up to a configured max_batch_size, satellite endpoints return the ephemeris and upcoming passes over a latitude and longitude, and organization tooling covers scoped API keys, users and invitations, platform metrics, and billing usage and invoices.

## For AI agents

Register and update Hubble devices, pull or decode their packets, set up packet webhooks, check upcoming satellite passes, and read organization metrics and billing.

## Scope

Does not manufacture or flash device firmware, provide cellular connectivity, or analyse packet contents for you. Use for managing Hubble devices, their packet data, and organization settings only.

## Capabilities

- Register up to 1,000 new devices in one call with their encryption, names, tags, and install_locations
- Retrieve an organization's packets between start and end times, optionally for one device_id
- Decode raw advertisements into packets with the decode endpoint
- Register a webhook endpoint with a max_batch_size so decrypted packets are pushed to your server
- Look up upcoming satellite passes over a latitude and longitude and fetch the satellite ephemeris
- Provision, update, and delete API keys limited to scopes such as read-devices or read-packets
- Read API, packet, webhook, and device metrics plus billing usage, active devices, and invoices

## Use cases

### Agent fleet status checks

An AI agent supporting a Hubble device fleet needs to answer which devices reported recently and what they sent. Through Jentic it finds the list-devices and packet operations by intent, filters devices by their most recent packet time, and pulls packets for any device that looks quiet, with the JWT bearer key held by your own instance.

Example prompt: Call GET `/v2/org/{org_id}/devices` with sort_field set to most_recent_packet_ts and sort_ascending true, then GET `/v1/org/{org_id}/packets` with device_id set to the first device returned and a start time 24 hours ago

### Bulk device provisioning

Rolling out trackers to a new site means registering many devices at once. POST `/v2/org/{org_id}/devices` takes n_devices up to 1,000 with the required encryption setting, plus names, tags, and install_locations, and batch update and batch delete operations change or retire devices in groups.

Example prompt: Call POST `/v2/org/{org_id}/devices` with n_devices 50, the required encryption setting, and tags set to warehouse-east, then confirm with GET `/v2/org/{org_id}/devices`

### Packet delivery by webhook

Applications that act on device data should not poll. A webhook endpoint registered with a url and max_batch_size receives decrypted packets in batches, the test endpoint sends a sample delivery, and webhook metrics show how deliveries are going.

Example prompt: Call POST `/v1/org/{org_id}/webhooks` with url set to your ingest endpoint and max_batch_size 100, then POST `/v1/org/{org_id}/webhooks/{webhook_id}/test`

### Satellite pass planning

Field teams testing coverage want to know when a satellite will be overhead. The passes endpoint takes a latitude and longitude with optional min_altitude_angle and days_ahead and returns upcoming passes, and the ephemeris endpoint returns the orbital elements behind them.

Example prompt: Call GET `/v1/org/{org_id}/satellite/passes` with latitude 53.35 and longitude -6.26 and days_ahead 2, then list the pass times

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v2/org/{org_id}/devices` | List devices |
| POST | `/v2/org/{org_id}/devices` | Register new devices |
| GET | `/v1/org/{org_id}/packets` | Retrieve packets |
| POST | `/v1/org/{org_id}/packets/decode` | Decode packets |
| POST | `/v1/org/{org_id}/webhooks` | Create a webhook endpoint |
| GET | `/v1/org/{org_id}/satellite/passes` | Upcoming satellite passes |
| POST | `/v1/org/{org_id}/key` | Provision an API key |

## Key resources

- **Devices** — List, register, get, update, batch update, and delete devices
- **Packets** — Retrieve packets by time range or device and decode advertisements
- **Webhooks** — Create, list, update, test, and delete packet webhook endpoints
- **Satellites** — Satellite ephemeris and upcoming passes over a location
- **Organization** — API keys and scopes, users, invitations, metadata, platform metrics, and billing

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 55 / 100
  - Developer Experience & Jentic Compatibility: 72 / 100
  - AI-Readiness & Agent Experience: 59 / 100
  - Agent Usability: 94 / 100
  - Security: 75 / 100
  - AI Discoverability: 71 / 100
- **View full report:** https://jentic.com/apis/hubble.com/hubble/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Hubble by hand means creating a scoped JWT key, carrying org_id in the URL path, paging with the Continuation-Token header, and staying under per-endpoint and per-organization rate limits. Through Jentic you install once, import Hubble from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Hubble puts the organization and device ids in the URL path (`/v2/org/{org_id}/devices/{device_id}`), so a rule can pin your agent to one organization, or one device, and the operations you pick. You choose the operations it may call, so destructive ones like batch device deletion or API key provisioning are not included unless you add them.
- **Credential handling:** Your Hubble API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list my devices' or 'next satellite pass', and Jentic returns the matching Hubble operation with its input schema so the agent fills org_id, device_id, and time ranges correctly without browsing the reference docs.

## Related APIs

- **Blues Notehub API** — Cellular IoT device management and event routing
- **Particle Cloud API** — Device management and data for Particle hardware
- **Samsara API** — Fleet and asset telematics

## FAQ

### What authentication does the Hubble Platform API use?

Per its OpenAPI spec, the Hubble Platform API uses HTTP bearer authentication with a JWT API key created in the Hubble dashboard, and most paths also need your org_id. Keys can be limited to scopes such as read-devices, write-devices, or read-packets, and a key created without scopes gets all of them. Packet webhooks you host receive an HTTP-X-HUBBLE-TOKEN header so you can verify deliveries.

### Can I register many devices at once with the Hubble Platform API?

Yes. POST `/v2/org/{org_id}/devices` registers between 1 and 1,000 devices per call with n_devices and a required encryption setting, and can set names, tags, eid_rotation, and install_locations. PATCH and DELETE on the same path update or remove devices in bulk.

### What are the rate limits for the Hubble Platform API?

The spec states a leaky bucket limit of three requests per second per endpoint and 15 requests per second in total for your organization. Going over returns a 429, and Hubble recommends backoff retry logic.

### Is there a Hubble MCP server?

You don't need an MCP server to give your agent Hubble. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the device, packet, and satellite operations it needs, discovered on demand rather than loaded into its context up front.

### How do I retrieve device packets through Jentic?

Search Jentic for 'retrieve hubble device packets', load GET `/v1/org/{org_id}/packets`, and pass start and end times with an optional device_id, following the Continuation-Token header to page. Your instance attaches the bearer key at call time. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Hubble Platform API?

Yes. For example, allow only GET `/v2/org/{org_id}/devices/{device_id}` and GET `/v1/org/{org_id}/packets` for your org id, and the agent can check devices and read their packets but cannot delete devices, provision API keys, or invite users, and its calls are logged.