canonical: https://jentic.com/apis/balena.io/balena

# Balena Cloud API

Jentic publishes the only available OpenAPI specification for Balena Cloud API, keeping it validated and agent-ready. Deploy and manage containerized applications across fleets of Linux single-board computers using an OData-based REST API with 82 endpoints. The API covers fleet (application) management, device provisioning and state control, release tracking, environment variable configuration, tagging, API key management, and organization administration - all queryable with $filter, $select, $expand, $orderby, $top, and $skip operators.

## For AI agents

Deploy containers to IoT device fleets, manage device state and configuration, track releases, and configure environment variables across balena-managed Linux devices.

## Scope

Does not handle container image building, CI/CD pipelines, or device OS flashing - use for cloud-based fleet management and device configuration only.

## Capabilities

- Deploy containerized applications to fleets of Linux SBCs like Raspberry Pi and Jetson Nano
- Query device status, connectivity, and OS version across thousands of fleet members using OData filters
- Pin specific releases to devices for controlled rollout and rollback of container deployments
- Set environment variables at fleet, device, and service level for runtime configuration
- Tag devices and applications with custom metadata for fleet segmentation and filtering
- Provision new devices into organizations and transfer them between fleets

## Use cases

### AI Agent Fleet Deployment

AI agents orchestrate container deployments across IoT device fleets through Jentic's intent search. An agent searches for 'deploy release to device fleet', receives the POST /v7/release and PATCH /v7/application schemas, and pins a specific release commit to all fleet devices. Jentic handles bearer token authentication and OData query construction, letting the agent focus on deployment logic rather than API mechanics.

Example prompt: Create a new release for application ID 12345 and patch the application to pin all devices to that release commit hash

### Device Fleet Monitoring and Filtering

Monitor the health and state of large IoT fleets by querying the GET /v7/device endpoint with OData filters for online status, OS version, supervisor version, and custom tags. The API supports $expand to include related fleet and release data in a single request, enabling fleet-wide dashboards that identify devices needing attention - offline units, outdated OS versions, or failed update attempts.

Example prompt: Query all devices in application 12345 where is_online equals true and os_version does not match the latest, using $filter and $select to return only device name, UUID, and OS version

### Environment Variable Configuration Management

Configure runtime behavior of containerized services by setting environment variables at fleet, device, or service scope. The API exposes separate endpoints for each scope level - /v7/application_environment_variable, /v7/device_environment_variable, and /v7/device_service_environment_variable - allowing fine-grained configuration override hierarchies where device-level values take precedence over fleet defaults.

Example prompt: Set the environment variable 'API_ENDPOINT' to 'https://prod.example.com' on device environment variable endpoint for device ID 67890

### Multi-Organization Fleet Administration

Administer multiple organizations, each containing separate device fleets, through the /v7/organization endpoints. Create organizations, manage membership, and transfer applications between organizations. The API supports enterprise multi-tenancy patterns where a central operations team manages hundreds of customer-specific fleets with distinct access controls and billing boundaries.

Example prompt: List all organizations, then retrieve all applications under organization ID 456 with $expand=owns__device to count total devices per fleet

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v7/device | List all devices with OData query support |
| GET | /v7/application | List all fleet applications |
| POST | /v7/release | Create a new release for an application |
| PATCH | /v7/device({ID}) | Update device properties or pin a release |
| POST | /v7/device_environment_variable | Set a device environment variable |
| GET | /v7/organization | List organizations |
| POST | /v7/application | Create a new fleet application |
| GET | /v7/release({ID}) | Get release details by ID |

## Key resources

- **Application (Fleet)** — Create, configure, and manage container application fleets with release tracking
- **Device** — Provision, monitor, configure, and move devices across fleets with OData queries
- **Release** — Track container image releases and pin specific versions to devices or fleets
- **Environment Variables** — Set configuration at fleet, device, and service scope with override hierarchy
- **Organization** — Administer multi-tenant organizational boundaries and fleet ownership
- **Tags** — Apply custom metadata labels to devices, applications, and releases for segmentation

## Why Jentic

- **Setup:** Wiring Balena Cloud by hand means handling its bearer session-token or API-key auth and constructing OData query strings with $filter, $select, $expand, and paging operators for every device and fleet call. Through Jentic you install once, import the Balena Cloud API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Balena puts the resource id in the URL path (/v7/device({ID}), /v7/release({ID})), so a rule can pin your agent to one device or fleet: it can read that device's state and set its variables and nothing else. You choose the operations it may call, so destructive ones like deleting a device or an application are not included unless you add them.
- **Credential handling:** Your Balena session token or 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 'deploy a container release to my fleet' or 'list online devices', and Jentic returns the matching Balena operation with its OData query schema so the agent manages devices without learning OData syntax.

## Related APIs

- **Particle Cloud API** — Vertically integrated MCU cloud platform vs Balena's container-on-Linux approach
- **Golioth API** — MCU-focused IoT platform with LightDB state and OTA for Zephyr/ESP-IDF devices
- **ThingsBoard API** — Open-source IoT platform with rule engine, dashboards, and telemetry storage
- **Samsara API** — Fleet telematics and compliance tracking for vehicles and industrial assets

## FAQ

### Why is there no official OpenAPI spec for Balena Cloud API?

Balena does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Balena Cloud API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Balena Cloud API use?

The Balena Cloud API uses Bearer token authentication. You authenticate with either a session token (obtained via login) or a named API key created in the balena dashboard. Through Jentic, these tokens are stored in the encrypted Jentic One instance and agents receive scoped access without handling raw credentials.

### Can I query devices with complex filters using this API?

Yes. The API supports OData query parameters including $filter (e.g., is_online eq true), $select (return specific fields), $expand (include related resources), $orderby, $top, and $skip. For example, GET /v7/device?$filter=is_online eq true&$select=device_name,uuid,os_version returns only online devices with selected fields.

### How do I deploy a new container release to my fleet through Jentic?

Search Jentic for 'deploy release to balena fleet' to discover the POST /v7/release endpoint. Create a release with your container image reference, then PATCH /v7/application({ID}) to set the should_be_running__release field to your new release ID. All fleet devices will download and run the new containers automatically.

### What are the rate limits for the Balena Cloud API?

The Balena API enforces rate limits based on your plan tier. Free tier allows approximately 60 requests per minute. Paid plans support higher throughput. OData $expand queries count as a single request regardless of the number of related resources returned. Batch operations are recommended for fleet-wide changes.

### Can I set different environment variables per device in the same fleet?

Yes. Balena supports a three-level variable hierarchy: fleet-level (POST /v7/application_environment_variable), device-level (POST /v7/device_environment_variable), and service-level (POST /v7/device_service_environment_variable). Device-level values override fleet defaults, and service-level values override device defaults for specific containers.

### Can I limit what my agent is allowed to do with the Balena Cloud API?

Yes. Because you run Jentic One yourself, your own rules decide which Balena operations and credentials the agent can use. Since Balena puts the resource id in the URL path, such as /v7/device({ID}) and /v7/release({ID}), you can pin the agent to a single device or fleet so it only reads that device's state and sets its environment variables. You also choose the exact operations it may call, so destructive actions like deleting a device or an application stay out of reach unless you add them.