---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Event Management Topic Open API

# Event Management Topic Open API {#ariaid-title1}

* Release version: Yokohama
* 
* Updated January 30, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read

The Event Management Topic Open API provides an endpoint that enables you to send a topic through your message broker and store it on a ServiceNow instance.
Using this API you can store topics created through your message broker in the ServiceNow Topic \[topic\] table.

This API runs in the `sn-api-notif-mgmt` namespace and requires the sn_api_notif_mgmt.event_mgmt_integration role.

## Event Management Topic Open - POST /sn_api_notif_mgmt/topic {#ariaid-title2}

Creates a new record in the Topic \[sn_api_notif_mgmt_topic\] table and saves the passed topic information to that record.
Use this endpoint to synchronize topics created in your message-bus middleware with those in your ServiceNow instance.

When topics are created using this endpoint, the user_created field in the associated topic record is set to `false` and the type field is set to `egress`.

### URL format

Versioned URL: /api/sn_api_notif_mgmt/{api_version}/topic

Default URL: /api/sn_api_notif_mgmt/topic  
Note:  
Available versions are specified in the [REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs."). For scripted REST APIs there is additional version information on the [Scripted REST Service form](https://www.servicenow.com/docs/cpRBis~pwSIJPZVsP8Hkxw "The scripted REST API feature allows application developers to build custom web service APIs.").

### Supported request parameters

{#evt_man_top-POST-topic__entry__2}{#evt_man_top-POST-topic__version-not_optional-RESTAPI}

| Name | Description |
|-|-|
| api_version | Optional. Version of the endpoint to access. For example, <kbd class="ph userinput">v1</kbd> or <kbd class="ph userinput">v2</kbd>. Only specify this value to use an endpoint version other than the latest. Data type: String |
[Table 1. Path parameters]

{#evt_man_top-POST-topic__entry__6}

| Name | Description |
|-|-|
| None |   |
[Table 2. Query parameters]

{#evt_man_top-POST-topic__entry__10}

| Name | Description |
|-|-|
| contentQuery | Filter to apply to the payload of the event. This query is a deeper event filter that is used to find information such as event severity or ticket type. You can pass this parameter as a nested query. For example, for the following trouble ticket event payload, this query applies to the attributes that are in the <var class="keyword varname">"event"</var> object of the payload: { "eventId":"dc2003c2c3bb3550054e20bdc0013136", "@type":"Troubleticket", "eventType":"TroubleTicketCreateEvent", "event":{ "troubleTicket":{ "short_description":"Test payload", "severity":3, "ticketType":"incident" } } } This parameter supports the following conditions: * AND: such as` variable1=value1&variable2=value2&variable3=value3` * OR: such as `variable1=value1,value2,value3` * Hierarchical variables: such as `variable1.variable2.variable3=value1` {#evt_man_top-POST-topic__ul_ncp_nsm_zzb} For example: `"contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",` This field is mapped to the content_query field in the associated topic record. For additional information, refer to the [TMF688 Event Management API User Guide](https://www.tmforum.org/resources/standard/tmf688-event-management-api-user-guide-v4-0-0/). Data type: String |
| externalId | Unique external identifier for the topic, such as a GUID. This field is mapped to the topic_id field in the associated Topic record. Data type: String |
| headerQuery | Filter to apply to the event header properties. This query defines the type of events to listen to for the associated topic. You can pass this parameter as a nested query. This parameter supports the following conditions: * AND: such as` variable1=value1&variable2=value2&variable3=value3` * OR: such as `variable1=value1,value2,value3` * Hierarchical variables: such as `variable1.variable2.variable3=value1` For example: `"headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent"` This field is mapped to the header_query field in the associated topic record. For additional information, refer to the [TMF688 Event Management API User Guide](https://www.tmforum.org/resources/standard/tmf688-event-management-api-user-guide-v4-0-0/). Data type: String |
| name | Name of the topic. This field is mapped to the topic_name field in the associated topic record. Data type: String |
| namespace | Namespace for the topic. Empty if there is no associated namespace. This field is mapped to the namespace field in the associated topic record. Data type: String |
[Table 3. Request body parameters]

### Headers

The following request and response headers apply to this HTTP
action only, or apply to this action in a distinct way. For a list of general headers used
in the REST API, see [Supported REST API headers](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#evt_man_top-POST-topic__entry__22}{#evt_man_top-POST-topic__accept-JSON-only-entry-RESTAPI}{#evt_man_top-POST-topic__content_type-JSON-only-entry-RESTAPI}

| Header | Description |
|-|-|
| Accept | Data format of the response body. Only supports application/json. |
| Content-Type | Data format of the request body. Only supports application/json. |
[Table 4. Request headers]

{#evt_man_top-POST-topic__entry__28}

| Header | Description |
|-|-|
| None |   |
[Table 5. Response headers]

### Status codes

The following status codes apply to this HTTP action. For a
list of possible status codes used in the REST API, see [REST API HTTP response
codes](https://www.servicenow.com/docs/aXidvjgEVmS~V~ZL0h85lQ "REST (REpresentational State Transfer) is a simple stateless architecture that provides standards between computer systems on the web, making it easier for them to communicate with each other.").
{#evt_man_top-POST-topic__entry__32}{#evt_man_top-POST-topic__entry-200-status-code}{#evt_man_top-POST-topic__entry-500-status-code}

| Status code | Description |
|-|-|
| 201 | Successful. The request was successfully processed. |
| 400 | Topic external id passed already exists. Please pass the unique topic external id: Indicates that passed external ID already exists in the Topic table. Please pass the unique combination of topic name, header query, content query and namespace : Indicates that the combination of topic name, namespace, header query, and content query already exists. |
| 500 | Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error. |
[Table 6. Status codes]

### Response body parameters

{#evt_man_top-POST-topic__entry__40}

| Name | Description |
|-|-|
| contentQuery | Value of the content_query field in the created topic record. Data type: String |
| externalId | Value of the topic_id field in the created topic record. Data type: String |
| headerQuery | Value of the header_query field in the created Topic record. This field is used by the topic picker framework to determine what event messages should be sent to a topic. Data type: String |
| id | Sys_id of the created topic record. Data type: String |
| name | Name of the topic. Data type: String |
| namespace | Value of the namespace field in the created topic record. Data type: String |
[ ]

### cURL request

The following code example shows how to call this endpoint.

    curl "http://instance.servicenow.com/api/sn_api_notif_mgmt/topic" \
    --request POST \
    --header "Accept:application/json" \
    --user 'username':'password'
    --data
    {
      "name": "HighPriorityTroubleTicket",
      "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
      "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
      "externalId": "ext001",
      "namespace": "telecomEvents"
    }

Response:


    {
      "externalId": "ext001",
      "name": "HighPriorityTroubleTicket",
      "headerQuery": "eventType=TroubleTicketStatusChangeEvent,TroubleTicketAttributeChangeEvent",
      "contentQuery": "troubleTicket.ticketType=incident&troubleTicket.severity=1",
      "namespace": "telecomEvents",
      "id": "7ee9850443c3f550461f99612bb8f223"
    }