Skip to content

Tags Settings Endpoint

The tags settings endpoint is used to manage a user's tags. Tags can be used to organize and group mytokens, notifications, and calendars.

The URI of the tags endpoint can be obtained from the settings endpoint.

List Tags

List Tags Request

To list all tags of a user, the client sends a GET request to the tags endpoint. The request MUST include a mytoken with the read@settings:tags or settings:tags capability as authorization.

Example

GET /api/v0/settings/tags HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...

List Tags Response

A successful response returns the following parameters using the application/json media type:

Parameter Necessity Description
tags REQUIRED A JSON array of TagInfo objects

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tags": [
        {
            "tag": "production",
            "color": "#ff5733"
        },
        {
            "tag": "development",
            "color": "#33ff57"
        },
        {
            "tag": "CI",
            "color": "#3357ff"
        }
    ]
}

Create Tag

Create Tag Request

To create a new tag, the client sends a POST request to the tags endpoint with the tag name appended to the URL. The request MUST include a mytoken with the settings:tags capability as authorization.

Example

POST /api/v0/settings/tags/my-new-tag HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...

Create Tag Response

A successful response has the HTTP status code 204 and no content, unless the used mytoken has been rotated, in this case the updated mytoken is returned with a status code of 200.

Update Tag

Update Tag Request

To update an existing tag (e.g., change its name or color), the client sends a PUT request to the tags endpoint with the current tag name appended to the URL and adds the following parameters using the application/json format in the HTTP request entity-body:

Parameter Necessity Description
tag OPTIONAL The new tag name (to rename the tag)
color OPTIONAL The new color for the tag (e.g., hex color code)

At least one of tag or color must be provided. The request MUST include a mytoken with the settings:tags capability as authorization.

Renaming a tag

PUT /api/v0/settings/tags/old-name HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...
Content-Type: application/json

{
    "tag": "new-name"
}

Changing a tag's color

PUT /api/v0/settings/tags/my-tag HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...
Content-Type: application/json

{
    "color": "#ff9900"
}

Update Tag Response

A successful response has the HTTP status code 204 and no content, unless the used mytoken has been rotated, in this case the updated mytoken is returned with a status code of 200.

Delete Tag

Delete Tag Request

To delete a tag, the client sends a DELETE request to the tags endpoint with the tag name appended to the URL. The request MUST include a mytoken with the settings:tags capability as authorization.

Warning

Deleting a tag will remove it from all mytokens, notifications, and calendars that are using it.

Example

DELETE /api/v0/settings/tags/obsolete-tag HTTP/1.1
Host: mytoken.example.com
Authorization: Bearer eyJhbGcio...

Delete Tag Response

A successful response has the HTTP status code 204 and no content, unless the used mytoken has been rotated, in this case the updated mytoken is returned with a status code of 200.

Last update: March 30, 2026 14:00:08
Back to top