{"openapi":"3.1.0","info":{"title":"Cumulocity Operations (BYOK) API","version":"0.1.0","description":"Cumulocity Operations (BYOK) lets an AI assistant read your own Cumulocity Operations data through the Cumulocity Operations API with a key you supply (tenant ID and user name written as tenantID/username (for example t0071234/alice)). Reads and device changes: 6 tools (list_devices, get_device, list_operations, get_operation, restart_device, request_configuration_upload). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-cumulocity-operations.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-cumulocity-operations/docs"},"termsOfService":"https://connectorbay.com/byok-cumulocity-operations/terms"},"servers":[{"url":"https://byok-cumulocity-operations.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-cumulocity-operations/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 devices of the tenant (managed objects with the c8y_IsDevice fragment) with id, name, type, owner, last update and ","description":"List devices of the tenant (managed objects with the c8y_IsDevice fragment) with id, name, type, owner, last update and the operations each device supports. Use for \"Which devices are in my Cumulocity tenant and what operations do they support\".","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"},"fragment_type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"c8y_IsDevice","description":"Only objects that have this fragment; c8y_IsDevice selects devices.","title":"Fragment Type"},"type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices of this type, for example c8y_Linux.","title":"Type"},"text":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices whose name or fields contain this text.","title":"Text"},"page_size":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many devices per page (1 to 2000).","title":"Page Size"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"}},"required":["tenant"],"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, owner, timestamps and supported operations. Use for \"Show the Cumulocity device 12345\"","description":"Get one device by id: name, type, owner, timestamps and supported operations. Use for \"Show the Cumulocity device 12345\".","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"},"device_id":{"description":"Cumulocity device id (managed object id).","maxLength":40,"title":"Device Id","type":"string"}},"required":["tenant","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_operations":{"post":{"operationId":"list_operations","summary":"List device operations (commands sent to devices) with status PENDING, EXECUTING, SUCCESSFUL or FAILED, newest first, fo","description":"List device operations (commands sent to devices) with status PENDING, EXECUTING, SUCCESSFUL or FAILED, newest first, for one device or the whole tenant. Use for \"Which operations are pending for Cumulocity device 12345\".","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"},"device_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only operations for this device id.","title":"Device Id"},"status":{"anyOf":[{"enum":["SUCCESSFUL","FAILED","EXECUTING","PENDING"],"type":"string"},{"type":"null"}],"default":null,"description":"Only operations in this state.","title":"Status"},"fragment_type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only operations that carry this fragment, for example c8y_Restart.","title":"Fragment Type"},"date_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only operations created at or after this ISO 8601 time.","title":"Date From"},"page_size":{"anyOf":[{"maximum":2000,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many operations per page (1 to 2000).","title":"Page Size"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Current Page"}},"required":["tenant"],"title":"list_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}},"/v1/tools/get_operation":{"post":{"operationId":"get_operation","summary":"Get one operation by id to see whether the device has executed it (status and failure reason). Use for \"Did Cumulocity o","description":"Get one operation by id to see whether the device has executed it (status and failure reason). Use for \"Did Cumulocity operation 20180 succeed\".","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"},"operation_id":{"description":"Operation id returned when it was created.","maxLength":40,"title":"Operation Id","type":"string"}},"required":["tenant","operation_id"],"title":"get_operationArguments","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/restart_device":{"post":{"operationId":"restart_device","summary":"Create a restart operation (c8y_Restart) for one device. The device picks it up and reboots, so this changes the device ","description":"Create a restart operation (c8y_Restart) for one device. The device picks it up and reboots, so this changes the device state and the device is briefly offline. The device must support the operation (see c8y_SupportedOperations from list_devices). Not for doors, locks, gates, alarms, cameras, vehicles or safety limits. Use for \"Restart Cumulocity device 12345\".","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"},"device_id":{"description":"Cumulocity device id (the managed object id returned by list_devices), for example '12345'.","maxLength":40,"title":"Device Id","type":"string"},"confirm":{"const":"yes","description":"Must be exactly yes, only after the user approved this change in chat.","title":"Confirm","type":"string"},"description":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Short human-readable note shown in the operation list, up to 200 characters.","title":"Description"}},"required":["tenant","device_id","confirm"],"title":"restart_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/request_configuration_upload":{"post":{"operationId":"request_configuration_upload","summary":"Create a c8y_SendConfiguration operation asking one device to upload its current configuration to the platform. The devi","description":"Create a c8y_SendConfiguration operation asking one device to upload its current configuration to the platform. The device runs the request and updates its stored configuration record, which changes the device's reported state. The device must support the operation (see c8y_SupportedOperations from list_devices). Not for doors, locks, gates, alarms, cameras, vehicles or safety limits. Use for \"Ask Cumulocity device 12345 to upload its current configuration\".","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"},"device_id":{"description":"Cumulocity device id (the managed object id returned by list_devices), for example '12345'.","maxLength":40,"title":"Device Id","type":"string"},"confirm":{"const":"yes","description":"Must be exactly yes, only after the user approved this change in chat.","title":"Confirm","type":"string"},"description":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Short human-readable note shown in the operation list, up to 200 characters.","title":"Description"}},"required":["tenant","device_id","confirm"],"title":"request_configuration_uploadArguments","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}}}}