Fields

Article objects have the following fields and links:

Fields

field name description
subject the subject of the article
position the position of the article as displayed in the support center
quickcode code used in the agent to quickly add article content to a case
keywords keywords in the article
publish_at date the article is to be published
created_at date the article was created
updated_at date the article was updated
body the content of the article (HTML formatted)
body_email email specific content
body_email_auto true/false to use content from body
body_chat chat specific content
body_chat_auto true/false to use content from body
body_web_callback chat specific content
body_web_callback_auto true/false to use content from body
body_twitter twitter specific content
body_twitter_auto true/false to use content from body
body_qna QNA specific content
body_qna_auto true/false to use content from body
body_phone phone specific content
body_phone_auto true/false to use content from body
body_facebook facebook specific content
body_facebook_auto true/false to use content from body
rating The percentage of people who found the article helpful
rating_count The number of ratings given to the article
rating_score The number of people who found the article helpful
public_url The publicly accessible URL for this article
in_support_center true/false to display the article in the support center
internal_notes notes to the agent using the article
locale the ISO language code of the article
available_locales a list of ISO language codes corresponding to all available translations for the article

Links

rel class embeddable? description
self article no this article
topic topic no the topic to which this article is assigned
translations article_translation no the translation(s) for this article
created_by user yes user who created this article
updated_by user yes user who last updated this article
brands brand yes array of brand links associated to article, only on individual article get

List

Retrieve a paginated list of all articles.

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

Request Headers

header name description
Accept-Language ISO language code. Return only articles for this language code and return the translated fields for the subject, body, and channel-specific bodies.

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/articles \
    -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
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/articles?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/articles?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/articles?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "subject": "Awesome Subject",
        "body": "<p>Awesome apples</p>",
        "body_email": "Email for Awesome apples",
        "body_email_auto": false,
        "body_chat": "Awesome apples",
        "body_chat_auto": true,
        "body_web_callback": "<p>Awesome Apples</p>",
        "body_web_callback_auto": false,
        "body_twitter": "Awesome apples",
        "body_twitter_auto": true,
        "body_qna": "Awesome apples",
        "body_qna_auto": true,
        "body_phone": "Awesome apples",
        "body_phone_auto": true,
        "body_facebook": "Awesome apples",
        "body_facebook_auto": true,
        "rating": 75,
        "rating_count": 4,
        "rating_score": 3,
        "position": 1,
        "quickcode": "AWESOME",
        "in_support_center": true,
        "internal_notes": "Notes to the agent here",
        "publish_at": "2017-10-18T18:13:06Z",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:13:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/1",
            "class": "article"
          },
          "topic": {
            "href": "/api/v2/topics/1",
            "class": "topic"
          },
          "translations": {
            "href": "/api/v2/articles/1/translations",
            "class": "article_translation"
          },
          "attachments": {
            "href": "/api/v2/articles/1/attachments",
            "class": "attachment",
            "count": 1
          },
          "brands": null,
          "created_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "updated_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "subject": "How to make your customers happy",
        "body": "<strong>Use Desk.com</strong>",
        "body_email": "Email just doesn't cut it",
        "body_email_auto": false,
        "body_chat": "Use Desk.com",
        "body_chat_auto": true,
        "body_web_callback": "<strong>Use Desk.com</strong>",
        "body_web_callback_auto": false,
        "body_twitter": "Use Desk.com in 140 chars or less",
        "body_twitter_auto": false,
        "body_qna": "Use Desk.com",
        "body_qna_auto": true,
        "body_phone": "Use Desk.com",
        "body_phone_auto": true,
        "body_facebook": "Use Desk.com",
        "body_facebook_auto": true,
        "rating": 75,
        "rating_count": 4,
        "rating_score": 3,
        "position": 1,
        "quickcode": "AWESOME",
        "in_support_center": true,
        "internal_notes": "Notes to the agent here",
        "publish_at": "2017-10-18T18:13:06Z",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:13:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/2",
            "class": "article"
          },
          "topic": {
            "href": "/api/v2/topics/1",
            "class": "topic"
          },
          "translations": {
            "href": "/api/v2/articles/2/translations",
            "class": "article_translation"
          },
          "attachments": {
            "href": "/api/v2/articles/1/attachments",
            "class": "attachment",
            "count": 1
          },
          "brands": null,
          "created_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "updated_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single article.

GET https://yoursite.desk.com/api/v2/articles/: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/articles/: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
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
{
  "subject": "Awesome Subject",
  "body": "<p>Awesome apples</p>",
  "body_email": "Email for Awesome apples",
  "body_email_auto": false,
  "body_chat": "Awesome apples",
  "body_chat_auto": true,
  "body_web_callback": "<p>Awesome Apples</p>",
  "body_web_callback_auto": false,
  "body_twitter": "Awesome apples",
  "body_twitter_auto": true,
  "body_qna": "Awesome apples",
  "body_qna_auto": true,
  "body_phone": "Awesome apples",
  "body_phone_auto": true,
  "body_facebook": "Awesome apples",
  "body_facebook_auto": true,
  "rating": 75,
  "rating_count": 4,
  "rating_score": 3,
  "position": 1,
  "quickcode": "AWESOME",
  "in_support_center": true,
  "internal_notes": "Notes to the agent here",
  "publish_at": "2017-10-18T18:13:06Z",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1",
      "class": "article"
    },
    "topic": {
      "href": "/api/v2/topics/1",
      "class": "topic"
    },
    "translations": {
      "href": "/api/v2/articles/1/translations",
      "class": "article_translation"
    },
    "attachments": {
      "href": "/api/v2/articles/1/attachments",
      "class": "attachment",
      "count": 1
    },
    "brands": null,
    "created_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "updated_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Example Response with Branding

 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
{
  "subject": "Awesome Subject",
  "body": "<p>Awesome apples</p>",
  "body_email": "Email for Awesome apples",
  "body_email_auto": false,
  "body_chat": "Awesome apples",
  "body_chat_auto": true,
  "body_web_callback": "<p>Awesome Apples</p>",
  "body_web_callback_auto": false,
  "body_twitter": "Awesome apples",
  "body_twitter_auto": true,
  "body_qna": "Awesome apples",
  "body_qna_auto": true,
  "body_phone": "Awesome apples",
  "body_phone_auto": true,
  "body_facebook": "Awesome apples",
  "body_facebook_auto": true,
  "rating": 75,
  "rating_count": 4,
  "rating_score": 3,
  "position": 1,
  "quickcode": "AWESOME",
  "in_support_center": true,
  "internal_notes": "Notes to the agent here",
  "publish_at": "2017-10-18T18:13:06Z",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1",
      "class": "article"
    },
    "topic": {
      "href": "/api/v2/topics/1",
      "class": "topic"
    },
    "translations": {
      "href": "/api/v2/articles/1/translations",
      "class": "article_translation"
    },
    "attachments": {
      "href": "/api/v2/articles/1/attachments",
      "class": "attachment",
      "count": 1
    },
    "brands": [
      {
        "href": "/api/v2/brands/1",
        "class": "brand"
      }
    ],
    "created_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "updated_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Create

Create an article.

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

Applicable Roles

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

Example Curl Request

1
2
3
4
5
6
7
8
$ curl https://yoursite.desk.com/api/v2/articles \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subject":"How to make your customers happy","body":"<strong>Use Desk.com</strong>",
      "body_email": "Custom email body for article", "body_email_auto": false,
        "_links": { "topic": { "href": "/api/v2/topics/1", "class": "topic" } } }'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "subject": "How to create an article",
  "body": "Simply post here",
  "_links": {
    "topic": {
      "href": "/api/v2/topics/1",
      "class": "topic"
    }
  }
}

NOTE: Providing a link to a topic will assign this article to that topic.

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
{
  "subject": "How to make your customers happy",
  "body": "<strong>Use Desk.com</strong>",
  "body_email": "Email just doesn't cut it",
  "body_email_auto": false,
  "body_chat": "Use Desk.com",
  "body_chat_auto": true,
  "body_web_callback": "<strong>Use Desk.com</strong>",
  "body_web_callback_auto": false,
  "body_twitter": "Use Desk.com in 140 chars or less",
  "body_twitter_auto": false,
  "body_qna": "Use Desk.com",
  "body_qna_auto": true,
  "body_phone": "Use Desk.com",
  "body_phone_auto": true,
  "body_facebook": "Use Desk.com",
  "body_facebook_auto": true,
  "rating": 75,
  "rating_count": 4,
  "rating_score": 3,
  "position": 1,
  "quickcode": "AWESOME",
  "in_support_center": true,
  "internal_notes": "Notes to the agent here",
  "publish_at": "2017-10-18T18:13:06Z",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1",
      "class": "article"
    },
    "topic": {
      "href": "/api/v2/topics/1",
      "class": "topic"
    },
    "translations": {
      "href": "/api/v2/articles/1/translations",
      "class": "article_translation"
    },
    "attachments": {
      "href": "/api/v2/articles/1/attachments",
      "class": "attachment",
      "count": 1
    },
    "brands": null,
    "created_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "updated_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Update

Update an article.

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

Applicable Roles

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

Fields

field name description
subject the subject of this article
body the content of the article (HTML formatted)
body_email email-specific content
body_email_auto true/false to use content from body
brand_action whether to append or replace the brands of this article

Example Curl Request

1
2
3
4
5
6
7
$ curl https://yoursite.desk.com/api/v2/articles/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subject":"How to make your customers happy","body":"<strong>Use Desk.com</strong>",
       "body_email": "Custom email body for article", "body_email_auto": false, "brand_action": "append", "brand_ids": [2,3]}'

Example Request Body

This request also changes the topic to which this article is assigned by using _links.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "subject": "How to make your customers happy",
  "body": "<strong>Use Desk.com</strong>",
  "body_email": "Email just doesn't cut it",
  "body_email_auto": false,
  "body_twitter": "Use Desk.com in 140 chars or less",
  "body_twitter_auto": false,
  "brand_action": "append",
  "brand_ids": [
    2,
    3
  ],
  "_links": {
    "topic": {
      "href": "/api/v2/topics/2"
    }
  }
}

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
{
  "subject": "How to make your customers happy",
  "body": "<strong>Use Desk.com</strong>",
  "body_email": "Email just doesn't cut it",
  "body_email_auto": false,
  "body_chat": "Use Desk.com",
  "body_chat_auto": true,
  "body_web_callback": "<strong>Use Desk.com</strong>",
  "body_web_callback_auto": false,
  "body_twitter": "Use Desk.com in 140 chars or less",
  "body_twitter_auto": false,
  "body_qna": "Use Desk.com",
  "body_qna_auto": true,
  "body_phone": "Use Desk.com",
  "body_phone_auto": true,
  "body_facebook": "Use Desk.com",
  "body_facebook_auto": true,
  "rating": 75,
  "rating_count": 4,
  "rating_score": 3,
  "position": 1,
  "quickcode": "AWESOME",
  "in_support_center": true,
  "internal_notes": "Notes to the agent here",
  "publish_at": "2017-10-18T18:13:06Z",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1",
      "class": "article"
    },
    "topic": {
      "href": "/api/v2/topics/2",
      "class": "topic"
    },
    "translations": {
      "href": "/api/v2/articles/1/translations",
      "class": "article_translation"
    },
    "attachments": {
      "href": "/api/v2/articles/1/attachments",
      "class": "attachment",
      "count": 1
    },
    "brands": null,
    "created_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "updated_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Delete

Delete an article.

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

Applicable Roles

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

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/articles/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Attachment Fields

Attachment objects have the following fields and links:

Fields

field name description
file_name name of the file
content_type file's content type, e.g. image/png
size file size
url url to get the file; see Attachment URLs
erased_at when the attachment was erased; see Delete Attachment
created_at when the attachment was created
updated_at when the attachment was last updated

Article Attachment Links

rel class description
self attachment this attachment
article article the article to which this attachment belongs
erased_by user the user that erased this attachment
uploaded_by user the user who uploaded this attachment

Attachment URLs

The Attachment resource will contain a reference to an Attachment URL resource. You can fetch the actual file from this endpoint.

Download Attachment

GET https://yoursite.desk.com/api/v2/articles/:article_id/attachments/:id/url

Redirects to the location of the actual file. The URL will be in the Location HTTP header. This URL will expire after a short duration and should be used immediately.


List Attachments

Retrieve a paginated list of attachments for this article.

GET https://yoursite.desk.com/api/v2/articles/:article_id/attachments

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/articles/1/attachments \
    -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
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/attachments?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/articles/1/attachments?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/articles/1/attachments?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "file_name": "images.png",
        "content_type": "image/png",
        "size": 3499,
        "url": "https://yoursite.desk.com/api/v2/articles/1/attachments/1/url",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:13:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/1/attachments/1",
            "class": "attachment"
          },
          "article": {
            "href": "/api/v2/articles/1",
            "class": "article"
          },
          "uploaded_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      },
      {
        "file_name": "logo.png",
        "content_type": "logo/png",
        "size": 4399,
        "url": "https://yoursite.desk.com/api/v2/articles/1/attachments/2/url",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:13:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/1/attachments/2",
            "class": "attachment"
          },
          "article": {
            "href": "/api/v2/articles/1",
            "class": "article"
          },
          "uploaded_by": {
            "href": "/api/v2/users/1",
            "class": "user"
          }
        }
      }
    ]
  }
}

Show Attachment

Retrieve an attachment.

Show Article Attachment

GET https://yoursite.desk.com/api/v2/articles/:article_id/attachments/:id

Show Message Attachment

GET https://yoursite.desk.com/api/v2/articles/:article_id/message/attachments/:id

Show Reply Attachment

GET https://yoursite.desk.com/api/v2/articles/:article_id/replies/:reply_id/attachments/: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/articles/:article_id/attachments/: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
{
  "file_name": "images.png",
  "content_type": "image/png",
  "size": 3499,
  "url": "https://yoursite.desk.com/api/v2/articles/1/attachments/1/url",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/attachments/1",
      "class": "attachment"
    },
    "article": {
      "href": "/api/v2/articles/1",
      "class": "article"
    },
    "uploaded_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Create Attachment

Create a article attachment

Create a private article attachment.

POST https://yoursite.desk.com/api/v2/articles/:id/attachments

Applicable Roles

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

Fields

field name description
file_name name of the file
content_type file's content type, e.g. image/png
content base64 encoded file content

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/articles/:id/attachments \
  -u email:password \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"file_name": "favicon.png", "content_type": "image/png", "content": "iVBORw0KGgoAAAANSUhEUgAAABsAAAAXCAIAAAB1dKN5AAAAGXRFWHRTb2Z0\nd2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9i\nZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2Vo\naUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6\nbnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2\nLjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpS\nREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJk\nZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIg\neG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxu\nczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1s\nbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9S\nZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9w\nIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDo0\nNkEyOEM5RUE2REUxMUUyODc1NUM1OUZGMTlFMjEwNyIgeG1wTU06RG9jdW1l\nbnRJRD0ieG1wLmRpZDo0NkEyOEM5RkE2REUxMUUyODc1NUM1OUZGMTlFMjEw\nNyI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAu\naWlkOjg5ODY1RDg5QTZENzExRTI4NzU1QzU5RkYxOUUyMTA3IiBzdFJlZjpk\nb2N1bWVudElEPSJ4bXAuZGlkOjg5ODY1RDhBQTZENzExRTI4NzU1QzU5RkYx\nOUUyMTA3Ii8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4\nbXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+I+v80gAAAwJJREFUeNqklUtr\nU0EUx2fuvb1pmvSVmvpA2021tMXWoiLiY6MoFHQhgvYTFBTpZ+jChXHjwo3g\nUhe6EAuCoC1uRKVRulBbUFNSWvrC2rTN475mjmdmkkuSpg/t5SaczNzzu//z\nPzMTAwDI/14MCAficrAYyTHIepBlRNsVjhCPEw/E7XLiyu9/IELhZjITWTmb\nx98l3jwdtxk4HFxJN3YCUhcWCFIXBgiNj/x89ehTOpVrO3moh4HFiS1kgrET\nHOcCxGTABA5QS+LbAuJU+TkmcEqmsVWN0nglylMgUSyIqmXhvqG5Ag7HjLLS\nFEWNqOokDqT3IkeaBaobvhsWEyOUkN5G3YANHimWVCdEKWmO9KhAVM0BXyPO\nNpq0q14L6tRAa0B5BPmK8tIIMC7GJU5ALZf/WVh3HFYdCRkh09doauR4RI+Y\nVP00vAJLvdwtgjIJxcHV5Wz82fjU+4SbczFH02hL1z5S2Bp1VdTHCaLLQNns\n5G0SjqiqUSAS5yYXR2Mj9rrl53AOya/zm7XUwH2DFEcSHSaaiMaxgptrS+nR\n2Ft73d75RkAioEwb3ZVondKATlecPPTLk7iPO3el4/zVzpqw+X1sZvhxPLPJ\nawzc3o7soFgcQDrrtWiAIiuD2z7tvPg8rZ67dLPn2sApFSO3tT1679ZLziuc\nMlpGHBvE4oCLfk9A4HAUP2GDppLLzBPrmFJ6ub+nOA2JHScOVtaoFifW2Byg\nKLB4LpdxVBAIGqG66rLMyN5wHmHqJRptJpbB4bDW3aDT0pzahqAKrKz7e36t\njDibWFZBYzRUQmyr1c5GjdZQhWOtpT0aDJkqfv7wI2fcn8K2JCeXVHzk2IHi\nLP3B3aFybf7bNJpOWVMTixgvzqxOxGex/Uuzqx9e//BwfQBZmE5FmsM3Bs/g\nk34W3fpfwco6sdvDc8mVyq/UtcH7fe29JRq3OcOra8w7sT7sbKWpqoGhi2W4\n7TXmtx3jWOnY6C/shmt7Tftru0+3Xrh+tL6pZuPDdDf/hRWvvwIMAJE9J8AO\nRSMOAAAAAElFTkSuQmCC\n"}' -k

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "file_name": "images.png",
  "content_type": "image/png",
  "size": 3499,
  "url": "https://yoursite.desk.com/api/v2/articles/1/attachments/1/url",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/attachments/1",
      "class": "attachment"
    },
    "article": {
      "href": "/api/v2/articles/1",
      "class": "article"
    },
    "uploaded_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Update Attachment

Update a article attachment

Update a private article attachment.

PUT https://yoursite.desk.com/api/v2/articles/:article_id/attachments/:id

Applicable Roles

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

Fields

field name description
file_name name of the file
content_type file's content type, e.g. image/png
content base64 encoded file content

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/articles/:id/attachments \
  -u email:password \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"file_name": "favicon.png", "content_type": "image/png", "content": "iVBORw0KGgoAAAANSUhEUgAAABsAAAAXCAIAAAB1dKN5AAAAGXRFWHRTb2Z0\nd2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9i\nZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2Vo\naUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6\nbnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2\nLjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpS\nREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJk\nZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIg\neG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxu\nczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1s\nbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9S\nZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9w\nIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDo0\nNkEyOEM5RUE2REUxMUUyODc1NUM1OUZGMTlFMjEwNyIgeG1wTU06RG9jdW1l\nbnRJRD0ieG1wLmRpZDo0NkEyOEM5RkE2REUxMUUyODc1NUM1OUZGMTlFMjEw\nNyI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAu\naWlkOjg5ODY1RDg5QTZENzExRTI4NzU1QzU5RkYxOUUyMTA3IiBzdFJlZjpk\nb2N1bWVudElEPSJ4bXAuZGlkOjg5ODY1RDhBQTZENzExRTI4NzU1QzU5RkYx\nOUUyMTA3Ii8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4\nbXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+I+v80gAAAwJJREFUeNqklUtr\nU0EUx2fuvb1pmvSVmvpA2021tMXWoiLiY6MoFHQhgvYTFBTpZ+jChXHjwo3g\nUhe6EAuCoC1uRKVRulBbUFNSWvrC2rTN475mjmdmkkuSpg/t5SaczNzzu//z\nPzMTAwDI/14MCAficrAYyTHIepBlRNsVjhCPEw/E7XLiyu9/IELhZjITWTmb\nx98l3jwdtxk4HFxJN3YCUhcWCFIXBgiNj/x89ehTOpVrO3moh4HFiS1kgrET\nHOcCxGTABA5QS+LbAuJU+TkmcEqmsVWN0nglylMgUSyIqmXhvqG5Ag7HjLLS\nFEWNqOokDqT3IkeaBaobvhsWEyOUkN5G3YANHimWVCdEKWmO9KhAVM0BXyPO\nNpq0q14L6tRAa0B5BPmK8tIIMC7GJU5ALZf/WVh3HFYdCRkh09doauR4RI+Y\nVP00vAJLvdwtgjIJxcHV5Wz82fjU+4SbczFH02hL1z5S2Bp1VdTHCaLLQNns\n5G0SjqiqUSAS5yYXR2Mj9rrl53AOya/zm7XUwH2DFEcSHSaaiMaxgptrS+nR\n2Ft73d75RkAioEwb3ZVondKATlecPPTLk7iPO3el4/zVzpqw+X1sZvhxPLPJ\nawzc3o7soFgcQDrrtWiAIiuD2z7tvPg8rZ67dLPn2sApFSO3tT1679ZLziuc\nMlpGHBvE4oCLfk9A4HAUP2GDppLLzBPrmFJ6ub+nOA2JHScOVtaoFifW2Byg\nKLB4LpdxVBAIGqG66rLMyN5wHmHqJRptJpbB4bDW3aDT0pzahqAKrKz7e36t\njDibWFZBYzRUQmyr1c5GjdZQhWOtpT0aDJkqfv7wI2fcn8K2JCeXVHzk2IHi\nLP3B3aFybf7bNJpOWVMTixgvzqxOxGex/Uuzqx9e//BwfQBZmE5FmsM3Bs/g\nk34W3fpfwco6sdvDc8mVyq/UtcH7fe29JRq3OcOra8w7sT7sbKWpqoGhi2W4\n7TXmtx3jWOnY6C/shmt7Tftru0+3Xrh+tL6pZuPDdDf/hRWvvwIMAJE9J8AO\nRSMOAAAAAElFTkSuQmCC\n"}' -k

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "file_name": "images.png",
  "content_type": "image/png",
  "size": 3499,
  "url": "https://yoursite.desk.com/api/v2/articles/1/attachments/1/url",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/attachments/1",
      "class": "attachment"
    },
    "article": {
      "href": "/api/v2/articles/1",
      "class": "article"
    },
    "uploaded_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Delete Attachment

Delete an attachment.

Delete requests will set erased_at and erased_by.

Delete a article attachment

DELETE https://yoursite.desk.com/api/v2/articles/:article_id/attachments/:id

Applicable Roles

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

Note: the user making the request must have permission to delete content. This can be set in the Admin.

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/articles/:article_id/attachments/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Translation Fields

Article Translation objects have the following fields and links:

Fields

field name description
locale article translation's locale
subject the subject of the article
body the content of the article (HTML formatted)
body_email email specific content
body_email_auto true/false to use content from body
body_chat chat specific content
body_chat_auto true/false to use content from body
body_web_callback chat specific content
body_web_callback_auto true/false to use content from body
body_twitter twitter specific content
body_twitter_auto true/false to use content from body
body_qna QNA specific content
body_qna_auto true/false to use content from body
body_phone phone specific content
body_phone_auto true/false to use content from body
body_facebook facebook specific content
body_facebook_auto true/false to use content from body
outdated whether or not the translation is out of date
publish_at date the article is to be published
created_at date the article was created
updated_at date the article was updated

Links

rel class description
self article_translation this translation

List Translations

Retrieve a paginated list of translations for this article.

GET https://yoursite.desk.com/api/v2/articles/:article_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/articles/1/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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/translations?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/articles/1/translations?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/articles/1/translations?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "locale": "en",
        "subject": "Awesome Subject",
        "body": "<p>Awesome apples</p>",
        "body_email": "Email for Awesome apples",
        "body_email_auto": true,
        "body_chat": "Awesome apples",
        "body_chat_auto": true,
        "body_web_callback": "<p>Awesome Apples</p>",
        "body_web_callback_auto": true,
        "body_twitter": "Awesome apples",
        "body_twitter_auto": true,
        "body_qna": "Awesome apples",
        "body_qna_auto": true,
        "body_phone": "Awesome apples",
        "body_phone_auto": true,
        "body_facebook": "Awesome apples",
        "body_facebook_auto": true,
        "outdated": false,
        "publish_at": "2017-10-18T18:13:06Z",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:13:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/1/translations/en",
            "class": "article"
          }
        }
      },
      {
        "locale": "es",
        "subject": "Spanish Translation",
        "body": "Traducción español aquí",
        "body_email": "Traducción español aquí",
        "body_email_auto": true,
        "body_chat": "Traducción español aquí",
        "body_chat_auto": true,
        "body_web_callback": "Traducción español aquí",
        "body_web_callback_auto": true,
        "body_twitter": "Traducción español aquí",
        "body_twitter_auto": true,
        "body_qna": "Traducción español aquí",
        "body_qna_auto": true,
        "body_phone": "Traducción español aquí",
        "body_phone_auto": true,
        "body_facebook": "Traducción español aquí",
        "body_facebook_auto": true,
        "outdated": false,
        "publish_at": "2017-10-18T18:13:06Z",
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:13:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/articles/1/translations/es",
            "class": "article"
          }
        }
      }
    ]
  }
}

Show Translation

Retrieve a single article translation.

GET https://yoursite.desk.com/api/v2/articles/:article_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/articles/1/translations/en \
    -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
{
  "locale": "en",
  "subject": "Awesome Subject",
  "body": "<p>Awesome apples</p>",
  "body_email": "Email for Awesome apples",
  "body_email_auto": true,
  "body_chat": "Awesome apples",
  "body_chat_auto": true,
  "body_web_callback": "<p>Awesome Apples</p>",
  "body_web_callback_auto": true,
  "body_twitter": "Awesome apples",
  "body_twitter_auto": true,
  "body_qna": "Awesome apples",
  "body_qna_auto": true,
  "body_phone": "Awesome apples",
  "body_phone_auto": true,
  "body_facebook": "Awesome apples",
  "body_facebook_auto": true,
  "outdated": false,
  "publish_at": "2017-10-18T18:13:06Z",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/translations/en",
      "class": "article"
    }
  }
}

Create Translation

Create an article translation.

POST https://yoursite.desk.com/api/v2/articles/:article_id/translations

Applicable Roles

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

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/articles/1/translations \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"locale": "ja", "subject":"Yo quiero Desk.com API v2", "body":"No hablo engles? Lea este."}'

Example Request Body

1
2
3
4
5
{
  "locale": "es",
  "subject": "Yo quiero Desk.com API v2",
  "body": "No hablo engles? Lea este."
}

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
{
  "locale": "es",
  "subject": "Spanish Translation",
  "body": "Traducción español aquí",
  "body_email": "Traducción español aquí",
  "body_email_auto": true,
  "body_chat": "Traducción español aquí",
  "body_chat_auto": true,
  "body_web_callback": "Traducción español aquí",
  "body_web_callback_auto": true,
  "body_twitter": "Traducción español aquí",
  "body_twitter_auto": true,
  "body_qna": "Traducción español aquí",
  "body_qna_auto": true,
  "body_phone": "Traducción español aquí",
  "body_phone_auto": true,
  "body_facebook": "Traducción español aquí",
  "body_facebook_auto": true,
  "outdated": false,
  "publish_at": "2017-10-18T18:13:06Z",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/translations/es",
      "class": "article"
    }
  }
}

Update Translation

Update an article translation.

PATCH https://yoursite.desk.com/api/v2/articles/:article_id/translations/:locale

Applicable Roles

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

Fields

Please see Update for details on the specific fields for each translation.

Example Curl Request

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

Example Request Body

1
2
3
{
  "subject": "Updated Spanish Translation"
}

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
{
  "locale": "es",
  "subject": "Updated Spanish Translation",
  "body": "Traducción español aquí",
  "body_email": "Traducción español aquí",
  "body_email_auto": true,
  "body_chat": "Traducción español aquí",
  "body_chat_auto": true,
  "body_web_callback": "Traducción español aquí",
  "body_web_callback_auto": true,
  "body_twitter": "Traducción español aquí",
  "body_twitter_auto": true,
  "body_qna": "Traducción español aquí",
  "body_qna_auto": true,
  "body_phone": "Traducción español aquí",
  "body_phone_auto": true,
  "body_facebook": "Traducción español aquí",
  "body_facebook_auto": true,
  "outdated": false,
  "publish_at": "2017-10-18T18:13:06Z",
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:13:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/articles/1/translations/en",
      "class": "article"
    }
  }
}

Delete Translation

Delete an article translation. The default translation cannot be deleted.

Delete a article translation

DELETE https://yoursite.desk.com/api/v2/articles/:article_id/translations/:locale

Applicable Roles

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

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/articles/:article_id/translations/:locale \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content