Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: Latest
title: Cumulocity Notification 2.0 API
x-logo:
url: https://www.cumulocity.com/docs/images/logo-platform.svg
backgroundColor: '#F8F8F8'
altText: Cumulocity
href: https://www.cumulocity.com/api
description: '# REST implementation
This section describes the aspects common to all REST-based interfaces of Cumulocity. The interfaces are based on the Hypertext Transfer Protocol 1.1 using HTTPS. ## HTTP usage
### Application management
Cumulocity uses a so-called "application key" to distinguish requests coming from devices and traffic from applications. If you write an application, pass the following header as part of all requests:
```markup
X-Cumulocity-Application-Key:
```
For example, if you registered your application in the Cumulocity Administration application with the key "myapp", your requests should contain the header:
```markup
X-Cumulocity-Application-Key: myapp
```
This makes your application subscribable and billable. If you implement a device, do not pass the key. > **ⓘ Info:** Make sure that you pass the key in **all** requests coming from an application. If you leave out the key,
> the request will be considered as a device request, and the corresponding device will be marked as "available". ### Limited HTTP clients
If you use an HTTP client that can only perform GET and POST methods in HTTP, you can emulate the other methods through an additional "X-HTTP-METHOD" header. Simply issue a POST request and add the header, specifying the actual REST method to be executed. For example, to emulate the "PUT" (modify) method, you can use:
```http
POST ... X-HTTP-METHOD: PUT
```
### Processing mode
Every update request (PUT, POST, DELETE) executes with a so-called *processing mode*. The processing modes are as follows:
|Processing mode|Description|
|---|---|
|PERSISTENT (default)|Stores data in the Cumulocity database and sends data to the Streaming Analytics engine. Afterwards, Cumulocity returns the result of the request. This is the default mode.|
|TRANSIENT|Sends data to the Streaming Analytics engine and immediately returns the results asynchronously but does not store data in Cumulocity’s database. This mode saves storage and processing costs and is useful for example when tracking devices in real time without requiring data to be stored.|
|QUIESCENT|Behaves similar to the persistent mode with the exception that no real-time notifications will be sent.|
|CEP|Behaves like the transient mode with the exception that no real-time notifications are sent.|
To explicitly control the processing mode of an update request, you can use the "X-Cumulocity-Processing-Mode" header with a value of either "PERSISTENT", "TRANSIENT", "QUIESCENT" or "CEP":
```markup
X-Cumulocity-Processing-Mode: PERSISTENT
```
> **ⓘ Info:** Events are always delivered to CEP/Apama for all processing modes. This is independent from real-time notifications. ### Authorization
All requests issued to Cumulocity are subject to authorization. To determine the required permissions, see the "Required role" entries for the individual requests. To learn more about the different permissions and the concept of ownership in Cumulocity, see Getting started > Technical concepts > Security aspects > Access control > Managing roles and assigning permissions in the Cumulocity user documentation. > **⚠️ Important:** In the Cumulocity API, each granular permission is identified by a unique “permission” string, which is prefixed with ROLE_ (for example, ROLE_ALARM_READ, ROLE_INVENTORY_ADMIN). Therefore, permissions are frequently referred to as “roles” throughout the API as well as in the configuration files. For example, the microservice manifest includes a requiredRoles field, which actually expects a permission string. See also the Glossary of the Cumulocity user documentation for the usage of the terms “permission” and “role” in the Cumulocity context. ### Media types
Each type of data is associated with an own media type. The general format of media types is:
```markup
application/vnd.com.nsn.cumulocity.+json;ver=;charset=UTF-8
```
Each media type contains a parameter `ver` indicating the version of the type.'
servers:
- description: Cumulocity tenant
url: https://<TENANT_DOMAIN>
security:
- Basic: []
- OAI-Secure: []
- SSO: []
- JWT-IAM: []
tags:
- name: Notification 2.0 API
description: The notification 2.0 API resource returns URIs and URI templates to collections of notifications, so that all notifications or notifications of a specified context and/or source device can be retrieved.
x-codegen-ignore: true
paths:
/notification2:
get:
operationId: getNotificationApiResource
tags:
- Notification 2.0 API
security:
- Basic: []
- OAI-Secure: []
- SSO: []
summary: Retrieve URIs to collections of notification subscriptions
description: 'Retrieve URIs and URI templates to collections of notification subscriptions.
Required roles
ROLE_NOTIFICATION_2_ADMIN'
x-code-samples:
- lang: cURL
source: 'curl --location --request GET "https://<TENANT_DOMAIN>/notification2" \
--header "Authorization: Basic <AUTHORIZATION>"
'
- lang: C#
source: 'var client = new RestClient("https://<TENANT_DOMAIN>/notification2");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic <AUTHORIZATION>");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
'
- lang: Java
source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.get(\"https://<TENANT_DOMAIN>/notification2\")\n .header(\"Authorization\", \"Basic <AUTHORIZATION>\").asString();\n"
- lang: Node.js
source: "var unirest = require(\"unirest\");\nvar req = unirest(\"GET\", \"https://<TENANT_DOMAIN>/notification2\")\n .headers({\n \"Authorization\": \"Basic <AUTHORIZATION>\"\n })\n .end(function (res) {\n if (res.error) throw new Error(res.error);\n console.log(res.raw_body);\n });\n"
- lang: Python
source: "import requests\n\nurl = \"https://<TENANT_DOMAIN>/notification2\"\nheaders = {\n \"Authorization\": \"Basic <AUTHORIZATION>\"\n}\nresponse = requests.request(\"GET\", url, headers=headers)\nprint(response.text.encode(\"utf8\"))\n"
responses:
'200':
description: The request has succeeded and the URIs are sent in the response.
content:
application/vnd.com.nsn.cumulocity.notificationapi+json:
schema:
$ref: '#/components/schemas/NotificationApiResource'
'401':
$ref: '#/components/responses/unauthorizedError'
'403':
$ref: '#/components/responses/accessDenied'
components:
schemas:
desc_self:
title: SelfURL
description: A URL linking to this resource.
type: string
format: uri
readOnly: true
error:
type: object
properties:
error:
description: The type of error returned.
type: string
message:
description: A human-readable message providing more details about the error.
type: string
info:
description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the error code reported.
type: string
NotificationSubscription:
type: object
required:
- context
- subscription
properties:
context:
description: 'The context within which the subscription is to be processed.
> **ⓘ Info:** If the value is `mo` (managed object), then `source` must also be provided in the request body.
'
type: string
minLength: 1
enum:
- mo
- tenant
fragmentsToCopy:
description: Transforms the data to *only* include specified custom fragments. Each custom fragment is identified by a unique name. If nothing is specified here, the data is forwarded as-is.
type: array
items:
type: string
id:
description: Unique identifier of the subscription.
type: string
readOnly: true
self:
$ref: '#/components/schemas/desc_self'
source:
description: The managed object to which the subscription is associated.
type: object
properties:
id:
$ref: '#/components/schemas/desc_objectId'
name:
$ref: '#/components/schemas/desc_objectName'
self:
$ref: '#/components/schemas/desc_self'
subscription:
type: string
description: 'The subscription name.
The name identifies the Messaging Service topic that messages for this subscription will be published to.
Several subscriptions can share the same name, which means that the same topic will receive messages for all those subscriptions.
See [topics and subscriptions](#section/Overview/Topics-and-subscriptions) for more details.
'
pattern: ^[a-zA-Z0-9]+$
minLength: 1
subscriptionFilter:
description: Applicable filters to the subscription.
type: object
properties:
apis:
type: array
description: 'For the `mo` (managed object) context, notifications from the `alarms`, `alarmsWithChildren`, `events`, `eventsWithChildren`, `managedobjects` (Inventory), `measurements` and `operations` (Device control) APIs can be subscribed to.
The `alarmsWithChildren` and `eventsWithChildren` APIs subscribe to alarms and events respectively from the managed object identified by the `source.id` field, and all of its descendant managed objects.
For the `tenant` context, notifications from the `measurements`, `alarms`, `events`, `managedobjects` (Inventory), and `operations` APIs can be subscribed to explicitly. The `measurements` API is not included when the `*` wildcard is used.
Note that `managedobjects` notifications in the `tenant` context currently only include notifications of new managed objects, not updates or deletions of existing ones.
For all contexts, the `*` (wildcard) value can be used to subscribe to notifications from all of the available APIs in that context, except that tenant wildcard subscriptions currently exclude the `measurements` API.
> **ⓘ Info:** The wildcard `*` cannot be used in conjunction with other values.
'
items:
type: string
enum:
- alarms
- alarmsWithChildren
- events
- eventsWithChildren
- managedobjects
- measurements
- operations
- '*'
typeFilter:
type: string
description: 'Used to match the `type` property of the data. This must either be a string to match one specific type exactly, or be an `or` OData expression, allowing the filter to match any one of a number of types.
> **ⓘ Info:** The use of a `type` attribute is assumed, for example when using only a string literal `''c8y_Temperature''` (or using `c8y_Temperature`, as quotes can be omitted when matching a single type) it is equivalent to a `type eq ''c8y_Temperature''` OData expression.
> **ⓘ Info:** Currently only the `or` operator is allowed when using an OData expression. Example usage is `''c8y_Temperature'' or ''c8y_Pressure''` which will match all the data with types `c8y_Temperature` or `c8y_Pressure`.
'
nonPersistent:
description: Indicates whether the messages for this subscription are persistent or non-persistent, meaning they can be lost if consumer is not connected.
type: boolean
default: false
example:
id: '102700509'
self: http://<TENANT_DOMAIN>/notification2/subscriptions/102700509
source:
name: Test Device
self: http://<TENANT_DOMAIN>/inventory/managedObjects/251982
id: '251982'
context: mo
subscription: testSubscription
subscriptionFilter:
apis:
- measurements
- events
typeFilter: '''c8y_Speed'' or ''c8y_LocationUpdate'''
fragmentsToCopy:
- c8y_MaxSpeedMeasurement
- c8y_Position
nonPersistent: false
desc_objectId:
title: ObjectId
description: Unique identifier of the object.
type: string
minLength: 1
NotificationApiResource:
type: object
properties:
self:
$ref: '#/components/schemas/desc_self'
notificationSubscriptions:
description: Collection of all notification subscriptions.
type: object
properties:
self:
$ref: '#/components/schemas/desc_self'
subscriptions:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/NotificationSubscription'
notificationSubscriptionsBySource:
description: Read-only collection of all notification subscriptions for a specific source object. The placeholder {source} must be a unique ID of an object in the inventory.
type: string
notificationSubscriptionsBySourceAndContext:
description: Read-only collection of all notification subscriptions of a particular context and a specific source object.
type: string
notificationSubscriptionsByContext:
description: Read-only collection of all notification subscriptions of a particular context.
type: string
example:
notificationSubscriptions:
self: https://<TENANT_DOMAIN>/notification2/subscriptions
subscriptions: null
notificationSubscriptionsBySource: https://<TENANT_DOMAIN>/notification2/subscriptions?source={source}
notificationSubscriptionsBySourceAndContext: https://<TENANT_DOMAIN>/notification2/subscriptions?source={source}&context={context}
notificationSubscriptionsByContext: https://<TENANT_DOMAIN>/notification2/subscriptions?context={context}
self: https://<TENANT_DOMAIN>/notification2
desc_objectName:
title: ObjectName
description: Human-readable name that is used for representing the object in user interfaces.
type: string
responses:
unauthorizedError:
description: Authentication information is missing or invalid.
content:
application/vnd.com.nsn.cumulocity.error+json:
schema:
$ref: '#/components/schemas/error'
example:
error: security/Unauthorized
message: 'Invalid credentials! : Bad credentials'
info: https://www.cumulocity.com/guides/reference-guide/#error_reporting
accessDenied:
description: Not enough permissions/roles to perform this operation.
content:
application/vnd.com.nsn.cumulocity.error+json:
schema:
$ref: '#/components/schemas/error'
example:
error: security/Forbidden
message: Access is denied.
info: https://www.cumulocity.com/guides/reference-guide/#error_reporting
securitySchemes:
Basic:
type: http
scheme: basic
description: 'The authorization header is formed as `Basic <Base64(<tenantID>/<c8yuser>:<password>)>`. For instance, if your tenantID, username and password are **t0071234**, **testuser** and **secret123** respectively, you can generate the Base64 string with the following command:
```shell
$ echo -n t0071234/testuser:secret123 | base64
```
and your authorization header would look like this:
```
"Authorization": "Basic dDAwNzEyMzQvdGVzdHVzZXI6c2VjcmV0MTIz"
```
'
OAI-Secure:
type: http
scheme: bearer
description: 'This is the recommended authorization method because it provides high security using authorization tokens to prove the identity of the user, and it is the default login mode on creating new tenants. This mode is an enhancement of the previous OAuth Internal authentication (available prior to 10.13.0).
For more details about OAI-Secure authentication, see [Platform administration > Authentication > Basic settings > Login settings](https://www.cumulocity.com/docs/authentication/basic-settings/#login-settings) in the Cumulocity user documentation.
'
SSO:
type: oauth2
description: "The login with SSO requires a correct configuration on the [Cumulocity side](https://www.cumulocity.com/docs/authentication/sso/). With the configuration, an additional button is available on the Login page. After clicking the button, the user is redirected to authenticate with the configured authorization server. On successful login, the user is redirected to Cumulocity.\n\nAuthentication details are exchanged using cookies. There are two parts to it, the first is the authentication cookie that is handled automatically by the Cumulocity platform. The second is the XSRF-TOKEN cookie. When a client receives the cookie, it should take the value and put it in the X-XSRF-TOKEN request header in all subsequent requests.\n\nThe flow of authenticating with authentication code grant is as follows:\n\n\n\nThe first request executed by the browser is:\n\n```http\nGET /tenant/loginOptions\nHost: https://<TENANT_DOMAIN>\nAccept: application/vnd.com.nsn.cumulocity.loginoptioncollection+json\n```\n\nResponse sample:\n\n```json\n{\n \"loginOptions\": [\n {\n \"buttonName\": \"Login with oauth\",\n \"grantType\": \"<AUTHORIZATION_CODE>\",\n \"initRequest\": \"https://<TENANT_DOMAIN>/tenant/oauth?response_type=code&tenant_id=<TENANT_ID>\",\n \"self\": \"https://<TENANT_DOMAIN>/tenant/loginOptions/oauth2\",\n \"type\": \"oauth2\"\n },\n ...\n ],\n \"self\": \"http://<TENANT_DOMAIN>/tenant/loginOptions/\"\n}\n```\n\nThe browser must invoke the request provided in the initRequest parameter.\n\nThe initRequest initiates the redirect, in which the user is prompted for credentials. After successful login, the user is redirected back to the browser, where it must capture the code request parameter. Then the request to exchange the code for the token is as follows:\n\n```http\nPOST /tenant/oauth?grant_type=authorization_code&code=<CODE>\nHost: https://<TENANT_DOMAIN>\n```\n\nA successful response will have no body but the following response headers:\n\n```\nSet-Cookie: authorization=<TOKEN>;\nSet-Cookie: XSRF-TOKEN=<XSRF-TOKEN>;\n```\n\nThe authorization cookie is valid for two weeks.\n"
flows:
clientCredentials:
tokenUrl: /tenant/oauth?grant_type=authorization_code&code=<CODE>
scopes: {}
JWT-IAM:
type: http
scheme: bearer
bearerFormat: JWT
description: 'This kind of authentication substitutes the JWT authentication with OAuth2 access tokens from your Identity and Access Management (IAM).
You can enable this in the [SSO configuration](https://www.cumulocity.com/docs/authentication/sso/).
The HTTP header must include:
```
"Authorization": "Bearer <Access token>"
```
When a request with a bearer token in the header is received, Cumulocity checks if the access token is from your IAM (that is, if authentication is enabled in your SSO configuration), and verifies the authenticity of
the token remotely against the IAM.
'
x-tagGroups:
- name: Platform
tags:
- Platform API
- name: Alarms
tags:
- Alarm API
- Alarm notification API
- Alarms
- name: Applications
tags:
- Application API
- Applications
- Application versions
- Application binaries
- Bootstrap user
- Current application
- name: Audits
tags:
- Audit API
- Audits
- name: Device control
tags:
- Device control API
- Device control notification API
- Operations
- Bulk operations
- Device credentials
- New device requests
- Device control via SMS
- name: Events
tags:
- Event API
- Event notification API
- Events
- Attachments
- name: Feature toggles
tags:
- Feature toggles API
- name: Identity
tags:
- Identity API
- External IDs
- name: Inventory
tags:
- Inventory API
- Inventory notification API
- Managed objects
- Binaries
- Child operations
- Query language
- name: Measurements
tags:
- Measurement API
- Measurement notification API
- Measurements
- Measurements specifics
- name: Notifications 2.0
tags:
- About notifications 2.0
- Notification 2.0 API
- Subscriptions
- Tokens
- name: Real-time notifications
tags:
- Real-time notification API
- name: Retentions
tags:
- Retention rules
- name: Tenants
tags:
- Tenant API
- Tenants
- Tenant applications
- Trusted certificates
- Device statistics
- Usage statistics
- Options
- Login options
- Login tokens
- System options
- name: Users
tags:
- User API
- Current User
- Users
- Groups
- Roles
- Inventory Roles
- Device Permissions
- name: Certificate
tags:
- Certificate authority
- Device enrollment
x-provenance:
method: harvested
publisher: Cumulocity
source: https://cumulocity.com/api/core/dist/c8y-oas.yml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)