Administrators and authenticated users with the correct permission area able to write data to the City directly through the API. This guide will focus on 2 aspects of writing data to the city:

  1. Configuring the city schema to support writing data.
  2. Writing data that matches a city's schema.

After authenticating to CNAPI2 using either your login credentials or your API key, you can make calls to the City. If you need help authenticating to the API, reference the Setting up a Postman Environment and Authenticating Guide.

1. Configuring a city schema to support writing data

At its core, the Cognitive City is built upon a graph database where data is stored as a network of elements and connections, instead of as a table with rows and columns. We recommend having a base understanding of graphs and networks before configuring a city schema and writing data.

The city schema defines the types of elements and connections that comprise the city. This section will focus on the Elements and Connections part of the Postman Collection:

We are going to follow an example where we want to use the city to capture:

  • Projects being worked on.
  • The objectives projects align with.

While working through this example, keep in mind that a schema is highly configurable and be aligned to whatever type of information is relevant to your scenario. For instance, we could model who worked on the project or keyword tags for the objective. An important point is that a schema is not set in stone, you can continually modify and refine it.

For our current example, we need to align the city schema to support Projects, Objectives and the relationships between them. Projects and Objectives are the types of elements we will have in the city (aka Element Types). The relationships between them are the types of connections in the city (aka Connection Types):


You can create new element types by using the "Add Element Type" call under the "Element Type" folder. For this call, you will need to specify information about the element types you want to create. To do this, click "Body" once you have opened the "Add Element Type" call:

When you open the body of the call, you will see an array of JSON objects. Each object specifies the details of the element type you want to create. This allows you to create multiple element types with a single API call. Note that we are specifying properties for the element types, like name and description. We can also specify which property appears as the label throughout the system. Again, this is highly configurable. For example, we are adding a property for priority on Objective but not Project:

Click "Send" and you should receive a return message with "success" and the newly created element types.

Just like we created the element types for Project and Objective, we need to create the connection type that models the relationship between a project and objective. To do this, we will use the "Add Connection Type" call and use the body to specify what connection types we want to add:

In the "Add Connection Type" body, we can specify the new relationships we want to add. We specify what element types a new connection type should tie together. Note that the directionality of connection types is important. For example, the way we set up the source and destination element types below will allow us to say that "Project aligns with Objective" but not "Objective aligns with Project". Just as with element types, we can change these configurations in the future.

When we click "Send", we should see "success" and the new connection types we just created:

2. Writing data that matches a city schema

Now that we have our schema in place with the necessary element types and connection types, we can start to add specific elements and connections. You can think of the previous step as creating the categories for the elements and connections of the city. This step focuses on creating instances of elements and connections that fall within the groups we created.

To create new elements, we will use the "Upsert Element" call under the "Element" folder. Click "body" when you open the call to specify details about the elements we are going create:

In the body, we have a single "upsertManyElements" call with an array of objects. Each object is a new element that we want to create. Note that the "target" part of the element object allows us to specify an ID and the "typeName" (aka element type) for a new element. Below we are creating a project and objective, as well as specifying property information, with a single call:

An import note is that we are "upserting" instead of just adding elements. This means that if an element already exists with the same ID in the same element type, it will update the existing element with this new data. If there is not an existing element that matches, it will create a new element. In this case, we are creating 2 new elements. Note that the response specifies how many elements were updated vs upserted:

Once we have created elements, we can connect them together with the "Upsert Connections" call:

In the body of the "Upsert Connections" call, we follow a similar format to the "Upsert Elements" call. We can create many connections with a single call, wich each object being a new connection. For each new connection, we must specify the source and destination node information as well as the type of connection we want to create. We can also add properties to connections. Note that we must adhere to the source and destination element types we configured while creating the connection:

Just like adding new elements, adding new connections follows an "upsert" model. When we send the call to create our new connection, the response specifies how many new connections were made vs existing ones updated:

We wrote data to the city that adheres to the schema we configured! This was a very simple example of 1 connection that tied together 2 element types. This same process can be applied to make as many different element and connection types. While this example was 1 project to 1 objective, a 1-to-1 relationship, we can apply this to elements with 1-to-many and many-to-many relationships.

Next Steps:

To learn how to read the information that you just wrote to the city, continue to the Reading Data with CNAPI2 Guide.