Create and manage device events

Create an event for a device, query and update events, attach a file to an event, and delete the event.

Use with an AI agent

This page is the agent skill cumulocity-handle-events. Save it as cumulocity-handle-events/SKILL.md in the skills folder of your agent: .agents/skills/ for Codex, GitHub Copilot, Cursor, and Gemini CLI, or .claude/skills/ for Claude Code. It builds on cumulocity-authentication: install that skill too.

View SKILL.md All skills

POST /event/events Create an event
GET /event/events Retrieve all events
PUT /event/events/{id} Update a specific event
POST /event/events/{id}/binaries Attach a file to a specific event
PUT /event/events/{id}/binaries Replace the attached file of a specific event
GET /event/events/{id}/binaries Retrieve the attached file of a specific event
GET /event/events/{id} Retrieve a specific event
DELETE /event/events/{id} Remove a specific event

Events in Cumulocity's domain model
Troubleshooting devices in Monitoring and controlling devices

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 for the concept.

Requirements

SKILLS:

Authenticate REST API requests

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 <device_id> for the managed object ID of the device and <event_id> for the ID of the event.

To create an event

Send a Create an event request:

POST /event/events
Content-Type: application/json
Accept: application/json

{
  "source": { "id": "<device_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 <event_id>.

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

Send a Retrieve all events request with the filters you need:

GET /event/events?source=<device_id>&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

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 request:

PUT /event/events/<event_id>
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

An event can have one attached file. The default size limit is 50 MiB.

Send an Attach a file to a specific event request with the content of the file as the request body:

POST /event/events/<event_id>/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 request with the same headers and the new content:

PUT /event/events/<event_id>/binaries
Content-Type: text/plain
Accept: application/json

sensor log line 3

The platform returns HTTP 201.

To read the attached file

Send a Retrieve the attached file of a specific event request:

GET /event/events/<event_id>/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 request:

GET /event/events/<event_id>

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

Send a Remove a specific event request:

DELETE /event/events/<event_id>

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.