{"openapi":"3.1.0","info":{"title":"balenaCloud (BYOK) API","version":"0.1.0","description":"balenaCloud (BYOK) lets an AI assistant read your own balenaCloud data through the balenaCloud API with a key you supply (balenaCloud API key (named API key or session token)). Read-only: 10 tools (whoami, list_fleets, get_fleet, list_devices, get_device, list_device_tags, list_releases, list_services, list_service_installs, list_organizations). The BYOK key travels with each request, is used for...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-balena.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-balena/docs"},"termsOfService":"https://connectorbay.com/byok-balena/terms"},"servers":[{"url":"https://byok-balena.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-balena/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/whoami":{"post":{"operationId":"whoami","summary":"Show the balenaCloud user the key belongs to: id, username and email. Use for \"Which balenaCloud account is my API key f","description":"Show the balenaCloud user the key belongs to: id, username and email. Use for \"Which balenaCloud account is my API key for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"whoamiArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_fleets":{"post":{"operationId":"list_fleets","summary":"List fleets (applications) you can access with name, slug, type, release tracking and creation time. Public fleets also ","description":"List fleets (applications) you can access with name, slug, type, release tracking and creation time. Public fleets also appear unless you filter them out. Use for \"Which balenaCloud fleets do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"OData $filter expression, for example \"is_online eq true\" or \"belongs_to__application eq 123456\".","title":"Filter"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,uuid,app_name,slug,application_type,should_track_latest_release,is_public,is_archived,created_at","description":"Comma-separated fields to return ($select). Available: id, uuid, app_name, slug, application_type, should_track_latest_release, is_public, is_host, is_archived, is_discoverable, created_at.","title":"Select"},"orderby":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"OData $orderby expression, for example 'app_name asc'.","title":"Orderby"},"top":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return ($top, 1 to 200).","title":"Top"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip ($skip).","title":"Skip"}},"title":"list_fleetsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_fleet":{"post":{"operationId":"get_fleet","summary":"Get one fleet by its slug (organization handle slash fleet name). Use for \"Show the balenaCloud fleet myorg/myfleet\".","description":"Get one fleet by its slug (organization handle slash fleet name). Use for \"Show the balenaCloud fleet myorg/myfleet\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Fleet slug, for example myorg/myfleet.","maxLength":200,"title":"Slug","type":"string"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,uuid,app_name,slug,application_type,should_track_latest_release,is_public,is_archived,created_at","description":"Comma-separated fields to return ($select). Available: id, uuid, app_name, slug, application_type, should_track_latest_release, is_public, is_host, is_archived, is_discoverable, created_at.","title":"Select"}},"required":["slug"],"title":"get_fleetArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_devices":{"post":{"operationId":"list_devices","summary":"List devices with name, uuid, status, online flag, last connectivity, OS and supervisor versions, addresses and CPU, mem","description":"List devices with name, uuid, status, online flag, last connectivity, OS and supervisor versions, addresses and CPU, memory and storage use. Filter by fleet, status or online state. Use for \"Which balenaCloud devices are offline\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"OData $filter expression, for example \"is_online eq true\" or \"belongs_to__application eq 123456\".","title":"Filter"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,uuid,device_name,status,overall_status,is_online,last_connectivity_event,os_version,supervisor_version,ip_address,public_address,cpu_usage,cpu_temp,memory_usage,memory_total,storage_usage,storage_total,created_at,is_active","description":"Comma-separated fields to return ($select). Available: id, uuid, device_name, status, overall_status, is_online, last_connectivity_event, is_connected_to_vpn, ip_address, mac_address, public_address, os_version, os_variant, supervisor_version, note, latitude, longitude, location, cpu_usage, cpu_temp, memory_usage, memory_total, storage_usage, storage_total, is_undervolted, created_at, is_active, belongs_to__application, is_running__release, is_pinned_on__release, should_be_running__release.","title":"Select"},"orderby":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"OData $orderby expression, for example 'device_name asc'.","title":"Orderby"},"top":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return ($top, 1 to 200).","title":"Top"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip ($skip).","title":"Skip"}},"title":"list_devicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_device":{"post":{"operationId":"get_device","summary":"Get one device by uuid with status, online flag, versions, addresses and resource use. Use for \"Show the balenaCloud dev","description":"Get one device by uuid with status, online flag, versions, addresses and resource use. Use for \"Show the balenaCloud device with uuid 0a1b2c3d4e5f60718293a4b5c6d7e8f9\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"uuid":{"description":"Device uuid as returned by list_devices.","maxLength":200,"title":"Uuid","type":"string"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,uuid,device_name,status,overall_status,is_online,last_connectivity_event,os_version,supervisor_version,ip_address,public_address,cpu_usage,cpu_temp,memory_usage,memory_total,storage_usage,storage_total,created_at,is_active","description":"Comma-separated fields to return ($select). Available: id, uuid, device_name, status, overall_status, is_online, last_connectivity_event, is_connected_to_vpn, ip_address, mac_address, public_address, os_version, os_variant, supervisor_version, note, latitude, longitude, location, cpu_usage, cpu_temp, memory_usage, memory_total, storage_usage, storage_total, is_undervolted, created_at, is_active, belongs_to__application, is_running__release, is_pinned_on__release, should_be_running__release.","title":"Select"}},"required":["uuid"],"title":"get_deviceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_device_tags":{"post":{"operationId":"list_device_tags","summary":"List device tags (key and value) for all devices or for the devices you filter, for example by device uuid. Use for \"Wha","description":"List device tags (key and value) for all devices or for the devices you filter, for example by device uuid. Use for \"What tags does balenaCloud device 0a1b2c3d4e5f60718293a4b5c6d7e8f9 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"OData $filter expression, for example \"device/uuid eq '0a1b2c3d4e5f60718293a4b5c6d7e8f9'\".","title":"Filter"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,device,tag_key,value","description":"Comma-separated fields to return ($select). Available: id, device, tag_key, value.","title":"Select"},"orderby":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"OData $orderby expression, for example 'tag_key asc'.","title":"Orderby"},"top":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return ($top, 1 to 200).","title":"Top"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip ($skip).","title":"Skip"}},"title":"list_device_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_releases":{"post":{"operationId":"list_releases","summary":"List releases with version, commit, status, source, build times and invalidated flag. Filter by fleet id. Use for \"What ","description":"List releases with version, commit, status, source, build times and invalidated flag. Filter by fleet id. Use for \"What are the latest releases of my balenaCloud fleet 123456\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"OData $filter expression, for example 'belongs_to__application eq 123456'.","title":"Filter"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,created_at,raw_version,semver,revision,commit,status,source,start_timestamp,end_timestamp,is_invalidated,release_version,note","description":"Comma-separated fields to return ($select). Available: id, created_at, belongs_to__application, raw_version, semver, revision, variant, commit, status, source, start_timestamp, end_timestamp, update_timestamp, is_invalidated, release_version, note.","title":"Select"},"orderby":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"OData $orderby expression, for example 'created_at desc'.","title":"Orderby"},"top":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return ($top, 1 to 200).","title":"Top"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip ($skip).","title":"Skip"}},"title":"list_releasesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_services":{"post":{"operationId":"list_services","summary":"List services (container names) defined in fleets. Filter by fleet name or id. Use for \"Which services does my balenaClo","description":"List services (container names) defined in fleets. Filter by fleet name or id. Use for \"Which services does my balenaCloud fleet run\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"OData $filter expression, for example \"application/app_name eq 'myfleet'\".","title":"Filter"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,created_at,application,service_name","description":"Comma-separated fields to return ($select). Available: id, created_at, application, service_name.","title":"Select"},"orderby":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"OData $orderby expression, for example 'service_name asc'.","title":"Orderby"},"top":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return ($top, 1 to 200).","title":"Top"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip ($skip).","title":"Skip"}},"title":"list_servicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_service_installs":{"post":{"operationId":"list_service_installs","summary":"List which services are installed on which devices. Filter by device uuid. Use for \"Which services are installed on bale","description":"List which services are installed on which devices. Filter by device uuid. Use for \"Which services are installed on balenaCloud device 0a1b2c3d4e5f60718293a4b5c6d7e8f9\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"OData $filter expression, for example \"device/uuid eq '0a1b2c3d4e5f60718293a4b5c6d7e8f9'\".","title":"Filter"},"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,created_at,device,installs__service","description":"Comma-separated fields to return ($select). Available: id, created_at, device, installs__service.","title":"Select"},"orderby":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"OData $orderby expression, for example 'id asc'.","title":"Orderby"},"top":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return ($top, 1 to 200).","title":"Top"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip ($skip).","title":"Skip"}},"title":"list_service_installsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_organizations":{"post":{"operationId":"list_organizations","summary":"List the organizations you belong to with name, handle, company and website. Use for \"Which balenaCloud organizations am","description":"List the organizations you belong to with name, handle, company and website. Use for \"Which balenaCloud organizations am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"select":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":"id,created_at,name,handle,company_name,website,industry","description":"Comma-separated fields to return ($select). Available: id, created_at, name, handle, company_name, website, industry, billing_account_code.","title":"Select"},"orderby":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"OData $orderby expression, for example 'name asc'.","title":"Orderby"},"top":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return ($top, 1 to 200).","title":"Top"},"skip":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip ($skip).","title":"Skip"}},"title":"list_organizationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}