Balena Cloud API

Name: Balena Cloud API
Brand: Balena Cloud API
Availability: InStock

★ 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.

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.

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 | sh

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 instance

Jentic 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

GET STARTED

Start building with Balena Cloud API

Explore with Jentic

View OpenAPI Document

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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

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.

Intent-based discovery

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.

Time to first call

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 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.

Balena Cloud API

Connect the Balena Cloud API to your agent

Capabilities

Start building with Balena Cloud API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs