{"openapi":"3.1.0","info":{"title":"Things Board Cloud (BYOK) API","version":"0.1.0","description":"Things Board Cloud (BYOK) lets an AI assistant read your own Things Board Cloud data through the Things Board Cloud API with a key you supply (ThingsBoard API key (thingsboard.cloud, ThingsBoard 4.3 or newer; EU accounts use eu.thingsboard.cloud)). Read-only: 10 tools (list_devices, get_device, list_device_types, list_device_profiles, list_device_profile_names, list_ota_packages,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-thingsboard.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-thingsboard/docs"},"termsOfService":"https://connectorbay.com/byok-thingsboard/terms"},"servers":[{"url":"https://byok-thingsboard.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-thingsboard/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/list_devices":{"post":{"operationId":"list_devices","summary":"List the tenant's devices with id, name, device type (profile name), label and creation time. totalElements gives the fl","description":"List the tenant's devices with id, name, device type (profile name), label and creation time. totalElements gives the fleet size. Use for \"Which devices are in my ThingsBoard tenant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"description":"How many entities per page (1 to 1000).","maximum":1000,"minimum":1,"title":"Page Size","type":"integer"},"page":{"description":"Page number, starting at 0.","maximum":100000,"minimum":0,"title":"Page","type":"integer"},"text_search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities whose name or main text fields contain this text.","title":"Text Search"},"sort_property":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example createdTime or name.","title":"Sort Property"},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","title":"Sort Order"},"type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices of this device type (profile name).","title":"Type"}},"required":["page_size","page"],"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 id: name, type, label, creation time and device profile id. Use for \"Show the ThingsBoard device 784f3","description":"Get one device by id: name, type, label, creation time and device profile id. Use for \"Show the ThingsBoard device 784f394c-42b6-435a-983c-b7beff2784f9\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Device id: the UUID shown as id.id by list_devices, for example '784f394c-42b6-435a-983c-b7beff2784f9'.","maxLength":60,"title":"Device Id","type":"string"}},"required":["device_id"],"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_types":{"post":{"operationId":"list_device_types","summary":"List the distinct device types in use in the tenant. Use for \"Which device types do my ThingsBoard devices have\".","description":"List the distinct device types in use in the tenant. Use for \"Which device types do my ThingsBoard devices have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_device_typesArguments","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_profiles":{"post":{"operationId":"list_device_profiles","summary":"List device profile summaries (the device models of the tenant) with id, name, type and transport type. Filter by transp","description":"List device profile summaries (the device models of the tenant) with id, name, type and transport type. Filter by transport. Use for \"Which device profiles does my ThingsBoard tenant define\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"description":"How many entities per page (1 to 1000).","maximum":1000,"minimum":1,"title":"Page Size","type":"integer"},"page":{"description":"Page number, starting at 0.","maximum":100000,"minimum":0,"title":"Page","type":"integer"},"text_search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities whose name or main text fields contain this text.","title":"Text Search"},"sort_property":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example createdTime or name.","title":"Sort Property"},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","title":"Sort Order"},"transport_type":{"anyOf":[{"enum":["DEFAULT","MQTT","COAP","LWM2M","SNMP"],"type":"string"},{"type":"null"}],"default":null,"description":"Only profiles using this transport: DEFAULT, MQTT, COAP, LWM2M or SNMP.","title":"Transport Type"}},"required":["page_size","page"],"title":"list_device_profilesArguments","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_profile_names":{"post":{"operationId":"list_device_profile_names","summary":"List the names and ids of all device profiles, optionally only those used by at least one device. Use for \"Which device ","description":"List the names and ids of all device profiles, optionally only those used by at least one device. Use for \"Which device profile names are actually in use in ThingsBoard\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"active_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only profiles referenced by the tenant's devices.","title":"Active Only"}},"title":"list_device_profile_namesArguments","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_ota_packages":{"post":{"operationId":"list_ota_packages","summary":"List the OTA firmware and software packages of the tenant with title, version, type, target device profile, file name, s","description":"List the OTA firmware and software packages of the tenant with title, version, type, target device profile, file name, size and checksum. Use for \"Which firmware packages are uploaded to my ThingsBoard tenant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"description":"How many entities per page (1 to 1000).","maximum":1000,"minimum":1,"title":"Page Size","type":"integer"},"page":{"description":"Page number, starting at 0.","maximum":100000,"minimum":0,"title":"Page","type":"integer"},"text_search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities whose name or main text fields contain this text.","title":"Text Search"},"sort_property":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Field to sort by, for example createdTime or name.","title":"Sort Property"},"sort_order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","title":"Sort Order"}},"required":["page_size","page"],"title":"list_ota_packagesArguments","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_telemetry_keys":{"post":{"operationId":"list_telemetry_keys","summary":"List the names of the time series (telemetry) keys a device has reported. Use for \"Which telemetry keys does ThingsBoard","description":"List the names of the time series (telemetry) keys a device has reported. Use for \"Which telemetry keys does ThingsBoard device 784f394c-42b6-435a-983c-b7beff2784f9 report\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Device id: the UUID shown as id.id by list_devices, for example '784f394c-42b6-435a-983c-b7beff2784f9'.","maxLength":60,"title":"Device Id","type":"string"}},"required":["device_id"],"title":"list_telemetry_keysArguments","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_attribute_keys":{"post":{"operationId":"list_attribute_keys","summary":"List the names of a device's attributes, across all scopes or one scope (SERVER_SCOPE, SHARED_SCOPE or CLIENT_SCOPE). Us","description":"List the names of a device's attributes, across all scopes or one scope (SERVER_SCOPE, SHARED_SCOPE or CLIENT_SCOPE). Use for \"Which attributes does ThingsBoard device 784f394c-42b6-435a-983c-b7beff2784f9 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Device id: the UUID shown as id.id by list_devices, for example '784f394c-42b6-435a-983c-b7beff2784f9'.","maxLength":60,"title":"Device Id","type":"string"}},"required":["device_id"],"title":"list_attribute_keysArguments","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_latest_telemetry":{"post":{"operationId":"get_latest_telemetry","summary":"Get the most recent value and timestamp of the given telemetry keys of a device. keys is required. Use for \"What are the","description":"Get the most recent value and timestamp of the given telemetry keys of a device. keys is required. Use for \"What are the latest temperature and humidity values of ThingsBoard device 784f394c-42b6-435a-983c-b7beff2784f9\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Device id: the UUID shown as id.id by list_devices, for example '784f394c-42b6-435a-983c-b7beff2784f9'.","maxLength":60,"title":"Device Id","type":"string"},"keys":{"description":"Comma-separated telemetry key names, for example 'temperature,humidity'.","maxLength":300,"title":"Keys","type":"string"}},"required":["device_id","keys"],"title":"get_latest_telemetryArguments","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_telemetry_range":{"post":{"operationId":"get_telemetry_range","summary":"Get historical telemetry values of a device for given keys between two timestamps, optionally aggregated (AVG, MIN, MAX,","description":"Get historical telemetry values of a device for given keys between two timestamps, optionally aggregated (AVG, MIN, MAX, SUM, COUNT) over an interval. Use for \"What was the hourly average temperature of ThingsBoard device 784f394c-42b6-435a-983c-b7beff2784f9 yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"Device id: the UUID shown as id.id by list_devices, for example '784f394c-42b6-435a-983c-b7beff2784f9'.","maxLength":60,"title":"Device Id","type":"string"},"keys":{"description":"Comma-separated telemetry key names.","maxLength":300,"title":"Keys","type":"string"},"start_ts":{"description":"Start of the range in milliseconds since epoch.","maximum":4102444800000,"minimum":0,"title":"Start Ts","type":"integer"},"end_ts":{"description":"End of the range in milliseconds since epoch.","maximum":4102444800000,"minimum":0,"title":"End Ts","type":"integer"},"limit":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Maximum data points per key (default 100).","title":"Limit"},"agg":{"anyOf":[{"enum":["NONE","AVG","MIN","MAX","SUM","COUNT"],"type":"string"},{"type":"null"}],"default":"NONE","description":"Aggregation: NONE, AVG, MIN, MAX, SUM or COUNT.","title":"Agg"},"interval":{"anyOf":[{"maximum":31536000000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Aggregation interval in milliseconds; required when agg is not NONE.","title":"Interval"},"order_by":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"ASC or DESC (default DESC).","title":"Order By"}},"required":["device_id","keys","start_ts","end_ts"],"title":"get_telemetry_rangeArguments","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}}}}