Balena Cloud API
★ Only Publicly Available OpenAPI DocumentIOTDevice Managementbearer82 EndpointsREST
For Agents
Deploy containers to IoT device fleets, manage device state and configuration, track releases, and configure environment variables across balena-managed Linux devices.
Use for: I need to deploy a new release to my device fleet, List all devices in my balena application that are currently online, I want to set an environment variable on a specific device, Check whether a device has downloaded the latest release
Not supported: Does not handle container image building, CI/CD pipelines, or device OS flashing — use for cloud-based fleet management and device configuration only.
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.
Install Jentic One Beta
Connect the Balena Cloud API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Balena Cloud API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Balena Cloud API.
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
Patterns agents use Balena Cloud API for, with concrete tasks.
★ 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.
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.
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.
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.
List all organizations, then retrieve all applications under organization ID 456 with $expand=owns__device to count total devices per fleet
Key Endpoints
82 endpoints — jentic publishes the only available openapi specification for balena cloud api, keeping it validated and agent-ready.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Balena session tokens and API keys are stored encrypted in the Jentic vault (MAXsystem). Agents receive scoped bearer tokens — raw API keys never enter the agent's context window.
Intent-based discovery
Agents search by intent (e.g., 'deploy a container to my IoT fleet') and Jentic returns matching Balena operations with their OData query schemas, so the agent can manage devices without learning OData syntax.
Time to first call
Direct Balena integration: 2-4 days for OData query construction, auth flow, and pagination handling. Through Jentic: under 1 hour — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Balena Cloud API through Jentic.
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 at https://app.jentic.com/sign-up.
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 MAXsystem vault 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.
GET STARTED