# Tags

You can use the API to get or set tags.

The Tag model

| Key         | Type   | Description                                                   |
| ----------- | ------ | ------------------------------------------------------------- |
| id          | String | The unique identifier for the tag which is given by Tiledesk. |
| tag         | String | The tag name.                                                 |
| color       | String | The tag hexadecimal color                                     |
| attributes  | Object | The custom attributes which are set for the tag.              |
| createdAt   | String | The time (ISO-8601 date string) when the tag was created.     |
| updatedAt   | String | The time (ISO-8601 date string) when the tag was updated.     |
| createdBy   | String | The unique identifier of the row creator                      |
| id\_project | String | The unique identifier of the project                          |

## Get all tags

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/tags`

Allows an account to list all the tags.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |

#### Query Parameters

| Name      | Type   | Description                                                                                                                   |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| sortField | string | <p>what field to sort the results by.</p><p><em>Default field is createdAt</em></p>                                           |
| direction | string | <p>sort direction: 1 or -1. Return the results in ascending (1) or descending (-1) order.</p><p><em>defaults to desc</em></p> |
| page      | number | what page of results to fetch. defaults to first page.                                                                        |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |

{% tabs %}
{% tab title="200 " %}

```
[
   {
      "_id":"5e67b8bafb930c0017aa4e42",
      "tag":"tag1",
      "color":"#66C549",
      "id_project":"5e5d40b2bd0a9b00179ff3cd",
      "createdBy":"5e09d16d4d36110017506d7f",
      "createdAt":"2020-03-10T15:56:42.374Z",
      "updatedAt":"2020-03-10T15:56:42.374Z",
      "__v":0
   },
   {
      "_id":"5e67b737fb930c0017aa4e40",
      "tag":"important",
      "color":"#43B1F2",
      "id_project":"5e5d40b2bd0a9b00179ff3cd",
      "createdBy":"5e09d16d4d36110017506d7f",
      "createdAt":"2020-03-10T15:50:15.759Z",
      "updatedAt":"2020-03-10T15:50:15.759Z",
      "__v":0
   },
```

{% endtab %}
{% endtabs %}

## Get a tag by id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/tags/:id`

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| id          | string | the tag identifier                                                                       |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

{% tabs %}
{% tab title="200 " %}

```
  {
      "_id":"5e67b737fb930c0017aa4e40",
      "tag":"important",
      "color":"#43B1F2",
      "id_project":"5e5d40b2bd0a9b00179ff3cd",
      "createdBy":"5e09d16d4d36110017506d7f",
      "createdAt":"2020-03-10T15:50:15.759Z",
      "updatedAt":"2020-03-10T15:50:15.759Z",
      "__v":0
   }
```

{% endtab %}
{% endtabs %}

## Create a new tag

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/tags`

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

#### Request Body

| Name       | Type   | Description               |
| ---------- | ------ | ------------------------- |
| tag        | string | the tag name              |
| color      | string | the tag color             |
| attributes | object | The tag custom attributes |

{% tabs %}
{% tab title="200 " %}

```
  {
      "_id":"5e67b737fb930c0017aa4e40",
      "tag":"important",
      "color":"#43B1F2",
      "id_project":"5e5d40b2bd0a9b00179ff3cd",
      "createdBy":"5e09d16d4d36110017506d7f",
      "createdAt":"2020-03-10T15:50:15.759Z",
      "updatedAt":"2020-03-10T15:50:15.759Z",
      "__v":0
   }
```

{% endtab %}
{% endtabs %}

## Update a tag by id

<mark style="color:orange;">`PUT`</mark> `https://api.tiledesk.com/v3/:project_id/tags/:id`

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The id is the tag indentifier.                                                           |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

#### Request Body

| Name       | Type   | Description               |
| ---------- | ------ | ------------------------- |
| tag        | string | the tag name              |
| color      | string | the tag color             |
| attributes | object | The tag custom attributes |

{% tabs %}
{% tab title="200 " %}

```
  {
      "_id":"5e67b737fb930c0017aa4e40",
      "tag":"important",
      "color":"#43B1F2",
      "id_project":"5e5d40b2bd0a9b00179ff3cd",
      "createdBy":"5e09d16d4d36110017506d7f",
      "createdAt":"2020-03-10T15:50:15.759Z",
      "updatedAt":"2020-03-10T15:50:15.759Z",
      "__v":0
   }
```

{% endtab %}
{% endtabs %}

## Delete a tag by id

<mark style="color:red;">`DELETE`</mark> `https://api.tiledesk.com/v3/:project_id/tags/:id`

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The id is the tag indentifier.                                                           |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |

{% tabs %}
{% tab title="200 " %}

```
...
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tiledesk.com/apis/rest-api/tags.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.