Topics

Topics are linked to Events and allow you to better organize the data flowing through your SaaS. Learn how to communicate with our API to create and manage your workspace topics.

The topic model

The topic model is extremely straightforward, containing only a few properties.

Properties

Name
id
Type
string
Description
Unique identifier for the topic.
Name
workspace_id
Type
string
Description
The id of the workspace the topic belongs to.
Name
name
Type
string
Description
The name for the topic.
Name
description
Type
string
Description
The description of the topic shown in the SDAPI app.
Name
event_count
Type
number
Description
The number of events associated with the topic.
Name
created
Type
timestamp
Description
Timestamp of when the topic was created on the platform.
Name
timestamp
Type
timestamp
Description
Timestamp of the API response.

POST/topics

Create a topic

Basic endpoint allowing you to add a new topic to your currently authenticated workspace.

Required attributes

Name
name
Type
string
Description
THe name for the topic. All topic names will be converted to lowercase.

Optional attributes

Name
description
Type
string
Description
The description of the topic shown in the SDAPI app.

Request

POST

/topics

curl https://api.observli.com/topics \
  -H "Authorization: Bearer {token}" \
  --data-raw '{
    "name": "signups",
    "description": "Track new user registrations"
  }'

Response

{
  "data": {
    "id": "q863r62",
    "workspace_id": "jpl056m",
    "name": "signups",
    "description": "Track new user registrations",
    "event_count": 0,
    "created": 1698263326
  },
  "status": 201,
  "timestamp": 1698263326
}

GET/topics/:id

Retrieve a topic

This endpoint allows you to retrieve a topic by providing the id of the model. Refer to the list at the top of this page to see which properties are included with event objects.

Request

GET

/topics/56dkkly

curl https://api.observli.com/topics/56dkkly \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "q863r62",
    "workspace_id": "jpl056m",
    "name": "signups",
    "description": "Track new user registrations",
    "event_count": 0,
    "created": 1698263326
  },
  "status": 201,
  "timestamp": 1698263326
}

PUT/topics/:id

Update a event

This endpoint allows you to perform an update on a topic.

Optional attributes

Name
description
Type
string
Description
The description of the topic shown in the SDAPI app.

Request

PUT

/topics/56dkkly

curl -X PUT https://api.observli.com/topics/56dkkly \
  -H "Authorization: Bearer {token}" \
  -d description="Updated topic description"

Response

{
  "data": {
    "id": "q863r62",
    "workspace_id": "jpl056m",
    "name": "signups",
    "description": "Updated topic description",
    "event_count": 0,
    "created": 1698263326
  },
  "status": 201,
  "timestamp": 1698263326
}

GET/topics

List all topics

This endpoint allows you to retrieve a list of all your workspace topics. By default, all topics will be returned.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of topics returned.

Request

GET

/topics

curl -G https://api.observli.com/topics \
  -H "Authorization: Bearer {token}" \
  -d active=true \
  -d limit=10

Response

{
  "data": [
    {
      "id": "q863r62",
      "workspace_id": "jpl056m",
      "name": "signups",
      "description": "Updated topic description",
      "event_count": 0,
      "created": 1698263326
    },
    {
      "id": "2a1b2c3",
      // ...
    }
  ],
  "status": 200,
  "timestamp": 1698263326
}