Fields

Topic objects have the following fields and links:

Fields

field name description
name subject of the topic translated to the default locale
description an optional description of the topic
position topic's position in the Admin UI
allow_questions If true, allow customers to post questions about this topic in your Support Center
in_support_center If true, show this topic in your Support Center
created_at time when the topic was created
updated_at time when the topic was last updated at

Links

rel class embeddable? description
self topic no this topic
articles article no this topic's articles
translations topic_translation no this topic's translations

Articles have an additional field in the _links hash named count. count is the number of articles for that relationship -- for example, a topic with 5 articles will have 5 as the value of the count field within the articles link. Your application can make fewer requests by taking advantage of this field -- there's no reason to request articles if there aren't any!


List

Retrieve a paginated list of all topics.

GET https://yoursite.desk.com/api/v2/topics

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Request Headers

header name description
Accept-Language ISO language code. Return only topics for this language code and return the translated fields for the name and description.

Fields

field name description
article_search[text] When calculating the article counts for each topic, count only articles that match this text string

Sorting

Sorting is supported by using sort_field and sort_direction parameters in your request.

  • sort_field - topic field on which you would like to sort
  • sort_direction - direction to sort - asc for ascending, desc for descending

The following fields can be used for sorting topics: id and position. The default sort field is id and the default direction is asc.

Parameters

The endpoint accepts an optional boolean parameter, in_support_center. If provided and set to true, the returned topics will be limited to those which are included in support center. If set to false, only topics not in the supoort center will be returned. By default, all topics are returned.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/topics \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/topics?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/topics?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/topics?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Customer Support",
        "description": "This is key to going from good to great",
        "position": 1,
        "allow_questions": true,
        "in_support_center": true,
        "created_at": "2017-10-08T18:18:06Z",
        "updated_at": "2017-10-13T18:18:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/topics/1",
            "class": "topic"
          },
          "articles": {
            "href": "/api/v2/topics/1/articles",
            "class": "article"
          },
          "translations": {
            "href": "/api/v2/topics/1/translations",
            "class": "topic_translation"
          }
        }
      },
      {
        "name": "Another Topic",
        "description": "Not the first one, but another one!",
        "position": 2,
        "allow_questions": true,
        "in_support_center": true,
        "created_at": "2017-10-08T18:18:06Z",
        "updated_at": "2017-10-13T18:18:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/topics/2",
            "class": "topic"
          },
          "articles": {
            "href": "/api/v2/topics/2/articles",
            "class": "article"
          },
          "translations": {
            "href": "/api/v2/topics/2/translations",
            "class": "topic_translation"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single topic.

GET https://yoursite.desk.com/api/v2/topics/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/topics/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "name": "Customer Support",
  "description": "This is key to going from good to great",
  "position": 1,
  "allow_questions": true,
  "in_support_center": true,
  "created_at": "2017-10-08T18:18:06Z",
  "updated_at": "2017-10-13T18:18:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/topics/1",
      "class": "topic"
    },
    "articles": {
      "href": "/api/v2/topics/1/articles",
      "class": "article"
    },
    "translations": {
      "href": "/api/v2/topics/1/translations",
      "class": "topic_translation"
    }
  }
}

Create

Create a topic.

POST https://yoursite.desk.com/api/v2/topics

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
name subject of the topic
description an optional description of the topic
allow_questions If true, allow customers to post questions about this topic in your Support Center
in_support_center If true, show this topic in your Support Center

Links

name relation description
self topic this topic

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/topics \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Social Media"}'

Example Request Body

1
2
3
4
5
{
  "name": "Social Media",
  "allow_questions": true,
  "in_support_center": true
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "name": "Social Media",
  "description": null,
  "position": 1,
  "allow_questions": true,
  "in_support_center": true,
  "created_at": "2017-10-18T18:18:18Z",
  "updated_at": "2017-10-18T18:18:18Z",
  "_links": {
    "self": {
      "href": "/api/v2/topics/1",
      "class": "topic"
    },
    "articles": {
      "href": "/api/v2/topics/1/articles",
      "class": "article"
    },
    "translations": {
      "href": "/api/v2/topics/1/translations",
      "class": "topic_translation"
    }
  }
}

Update

Update a topic.

PATCH https://yoursite.desk.com/api/v2/topics/:id

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
name subject of the topic
description an optional description of the topic
allow_questions If true, allow customers to post questions about this topic in your Support Center
in_support_center If true, show this topic in your Support Center
brand_action Whether to append or replace the brands of this topic
brand_ids An array of brand_ids to associate with this case. An empty array (using a brand_action of replace) will remove all brands from this topic.

Links

name relation description
self topic this topic

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/topics/1 \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"New Name", "brand_action" : "append", "brand_ids": [2,3]}'

Example Request Body

1
2
3
4
5
6
7
8
9
{
  "name": "New Name",
  "allow_questions": false,
  "brand_action": "append",
  "brand_ids": [
    2,
    3
  ]
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "name": "New Name",
  "description": null,
  "position": 1,
  "allow_questions": false,
  "in_support_center": true,
  "created_at": "2017-10-13T18:18:18Z",
  "updated_at": "2017-10-18T18:18:18Z",
  "_links": {
    "self": {
      "href": "/api/v2/topics/1",
      "class": "topic"
    },
    "articles": {
      "href": "/api/v2/topics/1/articles",
      "class": "article"
    },
    "translations": {
      "href": "/api/v2/topics/1/translations",
      "class": "topic_translation"
    }
  }
}

Delete

Delete a topic.

DELETE https://yoursite.desk.com/api/v2/topics/:id

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/topics/1 \
    -u email:password \
    -X DELETE

Example Response

1
204 No Content

List Brands

Retrieve a paginated list of brands for this topic.

GET https://yoursite.desk.com/api/v2/topics/:topic_id/brands

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/topics/:topic_id/brands \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/topics/1/brands?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/topics/1/brands?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/topics/1/brands?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Desk.com",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/topics/1/brands/1",
            "class": "brand"
          },
          "articles": {
            "href": "/api/v2/brands/1/articles",
            "class": "article"
          }
        }
      },
      {
        "name": "Alpha Inc",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/topics/1/brands/2",
            "class": "brand"
          },
          "articles": {
            "href": "/api/v2/brands/2/articles",
            "class": "article"
          }
        }
      }
    ]
  }
}

Translation Fields

Topic Translation objects have the following fields and links:

Fields

field name description
name topic's name translated to the locale
locale language code -- see our list of supported languages for details
created_at time when the translation was created
updated_at time when the translation was last updated

Links

rel class description
self topic_translation this translation

List Translations

Retrieve a paginated list of translations for this topic.

GET https://yoursite.desk.com/api/v2/topics/:topic_id/translations

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/topics/:topic_id/translations \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/topics/1/translations?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/topics/1/translations?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/topics/1/translations?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Customer Support",
        "locale": "en_us",
        "created_at": "2017-10-08T18:18:06Z",
        "updated_at": "2017-10-13T18:18:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/topics/1/translations/en_us",
            "class": "topic_translation"
          }
        }
      },
      {
        "name": "Japanese Translation",
        "locale": "ja",
        "created_at": "2017-10-18T18:17:18Z",
        "updated_at": "2017-10-18T18:17:18Z",
        "_links": {
          "self": {
            "href": "/api/v2/topics/1/translations/ja",
            "class": "topic_translation"
          }
        }
      }
    ]
  }
}

Show Translation

Retrieve a single topic translation.

GET https://yoursite.desk.com/api/v2/topics/:id/translations/:locale

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/topics/:id/translations/:locale \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "name": "Customer Support",
  "locale": "en_us",
  "created_at": "2017-10-08T18:18:06Z",
  "updated_at": "2017-10-13T18:18:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/topics/1/translations/en_us",
      "class": "topic_translation"
    }
  }
}

Create Translation

Create a topic translation.

POST https://yoursite.desk.com/api/v2/topics/:topic_id/translations

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
name subject of the topic
locale topic translation's locale

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/topics/1/translations \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Japanese", "locale": "ja"}'

Example Request Body

1
2
3
4
{
  "name": "Japanese",
  "locale": "ja"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "name": "Japanese",
  "locale": "ja",
  "created_at": "2017-10-18T18:18:18Z",
  "updated_at": "2017-10-18T18:18:18Z",
  "_links": {
    "self": {
      "href": "/api/v2/topics/1/translations/en_us",
      "class": "topic_translation"
    }
  }
}

Update Translation

Update a topic translation.

PATCH https://yoursite.desk.com/api/v2/topics/:id/translations/:locale

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

Please see Create Translation for details on the specific fields.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/topics/1/translations/ja \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Updated Japanese Translation"}'

Example Request Body

1
2
3
{
  "name": "Updated Japanese Translation"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "name": "Updated Japanese Translation",
  "locale": "ja",
  "created_at": "2017-10-13T18:18:18Z",
  "updated_at": "2017-10-18T18:18:18Z",
  "_links": {
    "self": {
      "href": "/api/v2/topics/1/translations/en_us",
      "class": "topic_translation"
    }
  }
}

Delete Translation

Delete a topic translation.

DELETE https://yoursite.desk.com/api/v2/topics/:id/translations/:locale

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/topics/1/translations/ja \
    -u email:password \
    -X DELETE \

Example Response

1
204 No Content