{"openapi":"3.1.0","info":{"title":"Cumulocity Telemetry (BYOK) API","version":"0.1.0","description":"Cumulocity Telemetry (BYOK) lets an AI assistant read your own Cumulocity Telemetry data through the Cumulocity Telemetry API with a key you supply (tenant ID and user name written as tenantID/username (for example t0071234/alice)). Read-only: 8 tools (get_current_tenant, list_alarms, get_alarm, list_events, get_event, list_measurements, list_applications, list_bulk_operations). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-cumulocity-telemetry.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-cumulocity-telemetry/docs"},"termsOfService":"https://connectorbay.com/byok-cumulocity-telemetry/terms"},"servers":[{"url":"https://byok-cumulocity-telemetry.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-cumulocity-telemetry/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/get_current_tenant":{"post":{"operationId":"get_current_tenant","summary":"Show the tenant you are connected to: name, domain name, parent tenant and whether it may create sub-tenants. Use for \"W","description":"Show the tenant you are connected to: name, domain name, parent tenant and whether it may create sub-tenants. Use for \"Which Cumulocity tenant am I connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"}},"required":["tenant"],"title":"get_current_tenantArguments","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_alarms":{"post":{"operationId":"list_alarms","summary":"List alarms with type, text, severity, status, occurrence count and the device they belong to, newest first. Filter by d","description":"List alarms with type, text, severity, status, occurrence count and the device they belong to, newest first. Filter by device, severity, status, type or time. Use for \"Which active critical alarms does my Cumulocity tenant have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 100).","title":"Page Size"},"source":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items for this device (managed object id, for example 12345).","title":"Source"},"type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this type (exact match).","title":"Type"},"severity":{"anyOf":[{"enum":["CRITICAL","MAJOR","MINOR","WARNING"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this severity.","title":"Severity"},"status":{"anyOf":[{"enum":["ACTIVE","ACKNOWLEDGED","CLEARED"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this status.","title":"Status"},"resolved":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True returns only cleared alarms, false returns all other alarms.","title":"Resolved"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items on or after this date or ISO 8601 date and time, for example 2026-10-01T00:00:00Z.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items before this date or ISO 8601 date and time.","title":"Date To"}},"required":["tenant"],"title":"list_alarmsArguments","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_alarm":{"post":{"operationId":"get_alarm","summary":"Get one alarm by id with type, text, severity, status, count, times and its device. Use for \"Show Cumulocity alarm 9001\"","description":"Get one alarm by id with type, text, severity, status, count, times and its device. Use for \"Show Cumulocity alarm 9001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"},"alarm_id":{"description":"Alarm id from list_alarms.","maxLength":40,"title":"Alarm Id","type":"string"}},"required":["tenant","alarm_id"],"title":"get_alarmArguments","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_events":{"post":{"operationId":"list_events","summary":"List events reported by devices with type, text, time and the device they belong to, newest first. Filter by device, typ","description":"List events reported by devices with type, text, time and the device they belong to, newest first. Filter by device, type or time. Use for \"What events did Cumulocity device 12345 report today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 100).","title":"Page Size"},"source":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items for this device (managed object id, for example 12345).","title":"Source"},"type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this type (exact match).","title":"Type"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items on or after this date or ISO 8601 date and time, for example 2026-10-01T00:00:00Z.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items before this date or ISO 8601 date and time.","title":"Date To"},"fragment_type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only events that contain this fragment (for example c8y_LocationUpdate).","title":"Fragment Type"}},"required":["tenant"],"title":"list_eventsArguments","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_event":{"post":{"operationId":"get_event","summary":"Get one event by id with type, text, time and its device. Use for \"Show Cumulocity event 7001\".","description":"Get one event by id with type, text, time and its device. Use for \"Show Cumulocity event 7001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"},"event_id":{"description":"Event id from list_events.","maxLength":40,"title":"Event Id","type":"string"}},"required":["tenant","event_id"],"title":"get_eventArguments","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_measurements":{"post":{"operationId":"list_measurements","summary":"List measurements (sensor readings) reported by devices for one device, type and time range, newest first. Each item car","description":"List measurements (sensor readings) reported by devices for one device, type and time range, newest first. Each item carries the series values as reported by the device. Use for \"What temperature readings did Cumulocity device 12345 send in the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 100).","title":"Page Size"},"source":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items for this device (managed object id, for example 12345).","title":"Source"},"type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this type (exact match).","title":"Type"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items on or after this date or ISO 8601 date and time, for example 2026-10-01T00:00:00Z.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items before this date or ISO 8601 date and time.","title":"Date To"},"value_fragment_type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only measurements that contain this fragment (for example c8y_Temperature).","title":"Value Fragment Type"},"value_fragment_series":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only measurements that contain this series inside the fragment (for example T).","title":"Value Fragment Series"}},"required":["tenant"],"title":"list_measurementsArguments","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_applications":{"post":{"operationId":"list_applications","summary":"List applications installed or available in the tenant (hosted web apps, microservices, external apps) with name, type, ","description":"List applications installed or available in the tenant (hosted web apps, microservices, external apps) with name, type, availability, context path and description. Use for \"Which microservices are deployed in my Cumulocity tenant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 100).","title":"Page Size"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only the application with this exact name.","title":"Name"},"type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this application type (comma-separate several).","title":"Type"}},"required":["tenant"],"title":"list_applicationsArguments","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_bulk_operations":{"post":{"operationId":"list_bulk_operations","summary":"List bulk operations (one operation scheduled for every device in a group) with group, start date, status and progress c","description":"List bulk operations (one operation scheduled for every device in a group) with group, start date, status and progress counters. Use for \"Which bulk operations are running in my Cumulocity tenant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tenant":{"description":"Your Cumulocity tenant host label: the part before .cumulocity.com, for example 'mytenant'.","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Tenant","type":"string"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Results per page (1 to 100).","title":"Page Size"}},"required":["tenant"],"title":"list_bulk_operationsArguments","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}}}}