openapi: 3.1.0
info:
  title: Balena Cloud API
  version: 'v7'
  description: |
    The balenaCloud REST API is the primary interface to the Balena platform.
    It exposes OData-style resources for devices, fleets (applications), releases,
    environment variables, organizations, and user accounts. Authentication uses a
    bearer token (session token or named API key) supplied in the
    `Authorization: Bearer <token>` header. Backward-compatible paths for v1-v6
    are translated to the newest version.
  contact:
    name: balenaCloud
    url: https://docs.balena.io/reference/api/overview/
servers:
  - url: https://api.balena-cloud.com/v7
    description: balenaCloud v7
  - url: https://api.balena-cloud.com/v6
    description: balenaCloud v6 (backward-compatible)
tags:
  - name: Devices
    description: IoT devices managed by balena
  - name: Applications
    description: Fleets (applications)
  - name: Releases
    description: Container image releases
  - name: Device Tags
    description: Tags associated with devices
paths:
  /device:
    get:
      summary: List devices
      description: |
        List devices using OData-style queries. Supports `$select`, `$filter`,
        `$expand`, `$top`, `$skip`, and `$orderby`.
      operationId: listDevices
      tags: [Devices]
      parameters:
        - { in: query, name: $select, schema: { type: string } }
        - { in: query, name: $filter, schema: { type: string } }
        - { in: query, name: $expand, schema: { type: string } }
        - { in: query, name: $top, schema: { type: integer } }
        - { in: query, name: $skip, schema: { type: integer } }
        - { in: query, name: $orderby, schema: { type: string } }
      responses:
        '200':
          description: A page of devices
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DeviceList' }
      security: [{ bearer: [] }]
    post:
      summary: Create a device
      operationId: createDevice
      tags: [Devices]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        '201':
          description: Created device
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Device' }
      security: [{ bearer: [] }]
  /device({id}):
    parameters:
      - { in: path, name: id, required: true, schema: { type: integer } }
    get:
      summary: Get a device by id
      operationId: getDevice
      tags: [Devices]
      parameters:
        - { in: query, name: $select, schema: { type: string } }
        - { in: query, name: $expand, schema: { type: string } }
      responses:
        '200':
          description: Device
          content:
            application/json:
              schema:
                type: object
                properties:
                  d:
                    type: array
                    items: { $ref: '#/components/schemas/Device' }
      security: [{ bearer: [] }]
    patch:
      summary: Modify a device
      operationId: updateDevice
      tags: [Devices]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object }
      responses:
        '200': { description: Updated }
      security: [{ bearer: [] }]
    delete:
      summary: Delete a device
      operationId: deleteDevice
      tags: [Devices]
      responses:
        '200': { description: Deleted }
      security: [{ bearer: [] }]
  /application:
    get:
      summary: List applications (fleets)
      operationId: listApplications
      tags: [Applications]
      parameters:
        - { in: query, name: $select, schema: { type: string } }
        - { in: query, name: $filter, schema: { type: string } }
        - { in: query, name: $expand, schema: { type: string } }
      responses:
        '200':
          description: A page of applications
          content:
            application/json:
              schema:
                type: object
                properties:
                  d:
                    type: array
                    items: { $ref: '#/components/schemas/Application' }
      security: [{ bearer: [] }]
    post:
      summary: Create an application (fleet)
      operationId: createApplication
      tags: [Applications]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [app_name, device_type]
              properties:
                app_name: { type: string }
                device_type: { type: string }
                organization: { type: integer }
      responses:
        '201':
          description: Created application
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Application' }
      security: [{ bearer: [] }]
  /application({id}):
    parameters:
      - { in: path, name: id, required: true, schema: { type: integer } }
    get:
      summary: Get an application
      operationId: getApplication
      tags: [Applications]
      responses:
        '200':
          description: Application
          content:
            application/json:
              schema:
                type: object
                properties:
                  d:
                    type: array
                    items: { $ref: '#/components/schemas/Application' }
      security: [{ bearer: [] }]
    delete:
      summary: Delete an application
      operationId: deleteApplication
      tags: [Applications]
      responses:
        '200': { description: Deleted }
      security: [{ bearer: [] }]
  /release:
    get:
      summary: List releases
      operationId: listReleases
      tags: [Releases]
      parameters:
        - { in: query, name: $select, schema: { type: string } }
        - { in: query, name: $filter, schema: { type: string } }
      responses:
        '200':
          description: A page of releases
          content:
            application/json:
              schema:
                type: object
                properties:
                  d:
                    type: array
                    items: { type: object }
      security: [{ bearer: [] }]
  /device_tag:
    get:
      summary: List device tags
      operationId: listDeviceTags
      tags: [Device Tags]
      parameters:
        - { in: query, name: $filter, schema: { type: string } }
      responses:
        '200':
          description: A page of device tags
          content:
            application/json:
              schema:
                type: object
                properties:
                  d:
                    type: array
                    items: { type: object }
      security: [{ bearer: [] }]
    post:
      summary: Create a device tag
      operationId: createDeviceTag
      tags: [Device Tags]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [device, tag_key, value]
              properties:
                device: { type: integer }
                tag_key: { type: string }
                value: { type: string }
      responses:
        '201':
          description: Created
      security: [{ bearer: [] }]
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Session token or named API key supplied as
        `Authorization: Bearer <token>`. Create named API keys at
        https://dashboard.balena-cloud.com/preferences/access-tokens.
  schemas:
    Device:
      type: object
      properties:
        id: { type: integer }
        uuid: { type: string }
        device_name: { type: string }
        device_type: { type: string }
        is_online: { type: boolean }
        ip_address: { type: string }
        os_version: { type: string }
        status: { type: string }
        belongs_to__application: { type: object }
        created_at: { type: string, format: date-time }
    DeviceList:
      type: object
      properties:
        d:
          type: array
          items: { $ref: '#/components/schemas/Device' }
    Application:
      type: object
      properties:
        id: { type: integer }
        app_name: { type: string }
        slug: { type: string }
        device_type: { type: string }
        organization: { type: object }
        created_at: { type: string, format: date-time }