--- name: cumulocity-handle-events description: "Create an event for a device, query and update events, attach a file to an event, and delete the event. Use when the user wants to create, find, update, or delete the events of a device, or attach a file to an event." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Create and manage device events Source: https://cumulocity.com/docs/skills/device-management/handle-events/ Sector: Skills, Device management & connectivity Release: Latest Description: Create an event for a device, query and update events, attach a file to an event, and delete the event. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) Events pass real-time information from devices to Cumulocity, for example, that a door was opened or that a device changed its location. An event has a type, a time when it occurred, a text that describes it, and the source managed object that it belongs to. It can contain custom fragments with more details, and one attached file, such as a log file. See [Events](https://cumulocity.com/docs/concepts/domain-model/#events) for the concept. > **Requirements:** > ROLES & PERMISSIONS: > > * To create, update, and delete events and attach files: ROLE_EVENT_ADMIN > * To query events and read attached files: ROLE_EVENT_READ The examples use `` for the managed object ID of the device and `` for the ID of the event. ### To create an event {#to-create-an-event} Send a [Create an event](https://cumulocity.com/api/core/#operation/postEventCollectionResource) request: ```http POST /event/events Content-Type: application/json Accept: application/json { "source": { "id": "" }, "type": "c8y_DoorOpenedEvent", "text": "Front door opened", "time": "2026-10-14T09:00:00.000Z" } ``` The properties `source`, `type`, `text`, and `time` are required. Add custom fragments with more details as needed. The platform returns HTTP 201 and the new event with its `id`. Note the `id` as ``. If the platform returns HTTP 422, the request body is invalid, for example, because one of the required properties is missing. ### To query the events of a device {#to-query-the-events-of-a-device} Send a [Retrieve all events](https://cumulocity.com/api/core/#operation/getEventCollectionResource) request with the filters you need: ```http GET /event/events?source=&type=c8y_DoorOpenedEvent&pageSize=100 ``` The platform returns HTTP 200 and the matching events in the `events` array. You can combine the following filters: * `source`: The managed object ID that the event belongs to. * `type`: The event type. The filter accepts one type per request. * `dateFrom` and `dateTo`: The time interval of the event occurrence, as ISO 8601 date and time, for example `dateFrom=2026-10-14T00:00:00.000Z&dateTo=2026-10-15T00:00:00.000Z`. `dateFrom` is inclusive, `dateTo` is exclusive. * `fragmentType`: Only events that contain this fragment, for example `c8y_IsBinary` for events with an attached file. * `fragmentValue`: Only events in which the fragment has this value. This filter works only together with `fragmentType` and only for fragments with a string value. * `revert`: With `dateFrom` or `dateTo`, the platform returns the newest events first. Set `revert=true` to get the oldest events first. ### To update an event {#to-update-an-event} You can change only the `text` and the custom fragments of an event. The `source`, `type`, and `time` cannot be changed after the event is created. Send an [Update a specific event](https://cumulocity.com/api/core/#operation/putEventResource) request: ```http PUT /event/events/ Content-Type: application/json Accept: application/json { "text": "Front door opened (verified)" } ``` The platform returns HTTP 200 and the event with the new `text`. If the platform returns HTTP 422, the request body contains a property that cannot be changed. If it returns HTTP 404, the event does not exist. ### To attach a file to an event {#to-attach-a-file-to-an-event} An event can have one attached file. The default size limit is 50 MiB. Send an [Attach a file to a specific event](https://cumulocity.com/api/core/#operation/postEventBinaryResource) request with the content of the file as the request body: ```http POST /event/events//binaries Content-Type: text/plain Accept: application/json sensor log line 1 sensor log line 2 ``` The `Content-Type` must correspond to the type of the file. For other files, send the request as `multipart/form-data` with two parts: the part `object` contains a JSON object with the `name` and the `type` of the file, and the part `file` contains the file. The platform returns HTTP 201 and a JSON object with the `source` (the ID of the event), the `type`, and the `name` of the file. If you send the file as the request body, the `name` is the ID of the event. If you send it as `multipart/form-data`, the `name` is the file name. If the platform returns HTTP 409, the event already has an attached file. To replace the file, send a [Replace the attached file of a specific event](https://cumulocity.com/api/core/#operation/putEventBinaryResource) request with the same headers and the new content: ```http PUT /event/events//binaries Content-Type: text/plain Accept: application/json sensor log line 3 ``` The platform returns HTTP 201. ### To read the attached file {#to-read-the-attached-file} Send a [Retrieve the attached file of a specific event](https://cumulocity.com/api/core/#operation/getEventBinaryResource) request: ```http GET /event/events//binaries ``` The platform returns HTTP 200 and the content of the file. If it returns HTTP 404, the event has no attached file. To see the details of the file, send a [Retrieve a specific event](https://cumulocity.com/api/core/#operation/getEventResource) request: ```http GET /event/events/ ``` The event contains the fragment `c8y_IsBinary` with the `name`, the `length`, and the `type` of the file. After a `multipart/form-data` upload, `length` is the size of the multipart request body, not the size of the file. ### To delete an event {#to-delete-an-event} Send a [Remove a specific event](https://cumulocity.com/api/core/#operation/deleteEventResource) request: ```http DELETE /event/events/ ``` The platform returns HTTP 204. It deletes the attached file together with the event. The deletion runs in the background, so the platform can return the response before all data of the event is deleted. If the platform returns HTTP 404, the event does not exist anymore. In the Device Management application, you see the events of a device in its **Events** tab, see [To view events](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#to-view-events). ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [POST /event/events](https://cumulocity.com/api/core/#operation/postEventCollectionResource): Create an event - [GET /event/events](https://cumulocity.com/api/core/#operation/getEventCollectionResource): Retrieve all events - [PUT /event/events/{id}](https://cumulocity.com/api/core/#operation/putEventResource): Update a specific event - [POST /event/events/{id}/binaries](https://cumulocity.com/api/core/#operation/postEventBinaryResource): Attach a file to a specific event - [PUT /event/events/{id}/binaries](https://cumulocity.com/api/core/#operation/putEventBinaryResource): Replace the attached file of a specific event - [GET /event/events/{id}/binaries](https://cumulocity.com/api/core/#operation/getEventBinaryResource): Retrieve the attached file of a specific event - [GET /event/events/{id}](https://cumulocity.com/api/core/#operation/getEventResource): Retrieve a specific event - [DELETE /event/events/{id}](https://cumulocity.com/api/core/#operation/deleteEventResource): Remove a specific event ## Linked from the documentation - [Cumulocity's domain model > Events](https://cumulocity.com/docs/concepts/domain-model/#events) - [Monitoring and controlling devices > Troubleshooting devices](https://cumulocity.com/docs/device-management-application/monitoring-and-controlling-devices/#troubleshooting-devices)