API

Tags

This document will help you understand and use the novem tagging features

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

Novem offers a set of basic tagging features to help you organise your data. The tags come in three types:

  • system - Tags predefined by novem that you cannot control, these are for things such as favourites and likes.
  • user - Your personal +-prefixed tags, private to you, for you to define and use.
  • category - Shared =-prefixed tags that publicly categorise your own visuals.

The tags are exposed in the API at a top level tags endpoint as well as under each of the items that you can apply the tag to, such as plots, mails, grids and repos.

Note: Novem user tags are personal, only you can see your tags and they are not shared with or across users.

Below is an overview of the main tag endpoints.

.
├── admin
│   └── tags
│       └── +user_tag
│           ├── color
│           ├── description
│           └── name
├── tags
│   ├── +user_tag
│   │   ├── code
│   │   │   ├── jobs
│   │   │   └── repos
│   │   └── vis
│   │       ├── docs
│   │       │   └── @colleague~readme_doc
│   │       ├── grids
│   │       │   └── @colleague~layout
│   │       ├── mails
│   │       ├── plots
│   │       │   └── @other_user~other_plot
│   │       └── views
│   └── fav
│       ├── code
│       │   ├── jobs
│       │   └── repos
│       └── vis
│           ├── docs
│           ├── grids
│           ├── mails
│           │   └── @some_user~some_mail
│           ├── plots
│           │   ├── @other_user~other_plot
│           │   └── @username~plot_name
│           └── views
└── users
    └── other_user
        └── vis
            └── plots
                └── other_plot
                    └── tags
                        ├── +user_tag
                        └── fav

As mentioned there are two types of valid tags on the novem platform, user tags and system tags.

The most common tag you will use are probably user tags. Usertags must always start with a + followed by a lowercase letter and then one or more lowercase letters, numbers, - and _.

Examples of valid tags:

  • +my_user_tag
  • +cat5
  • +sen-dev-stack

Examples of invalid tags:

  • abc
  • +5cat
  • +long_A

The novem system tags are special and only a few of them exist. They are defined by novem and not possible to change or modify.

There are currently 6 system tags:

  • fav a way to favourite a vis
  • like a way to like a vis
  • ignore hide a vis from your feed
  • wip mark a vis as work in progress (keeps it out of your own feed)
  • archived archive a vis
  • follow follow a vis for comment and data activity

Category tags start with a = and, unlike private user tags, are shared and publicly visible. They let you classify your own visuals into common, discoverable categories.

  • They can only be applied to your own visuals.
  • A visual may carry at most 5 category tags.
  • The name is global — everyone sees the same =finance category.

Naming follows the same rules as user tags (a lowercase letter, then lowercase letters, numbers, - and _), but with = instead of +: e.g. =finance, =q3-report.

To tag a novem vis you simply PUT the tag in the respective vis's tags folder. User tags will be automatically created if they don't already exist.

PUT/v1/vis/plots/test_plot/tags/+important

For example, the above tags your own plot called test_plot, with your user tag +important.

PUT/v1/users/my_colleague/vis/plots/kpi_report/tags/+important

And this is how you tag your colleague'skpi_report plot with the same tag.

To tag an e-mail you would simply perform the same action on the e-mail endpoint.

PUT/v1/vis/mails/daily_kpi_report/tags/+important

To list your tags you will find them available at the top level /tags endpoint. Simply navigate the structure and you'll find all visualizations and other items under their respective tags.

You may further customize your user tags with colors, names and descriptions. This is done with POST to the respective endpoints under the admin structure.

└── admin
    └── tags
        └── +important
            ├── color
            ├── description
            └── name

For example, if you were to create a new tag +important to tag things that were important to you, you could customize it as follows.

POST/v1/admin/tags/+important/color
orange-500 -- you can choose any novem color or a hex code
POST/v1/admin/tags/+important/name
Important
POST/v1/admin/tags/+important/description
Key business indicators
Next
Social