General information

This document is the documentation for using your BOSSDesk account through an API.

API URL

V2 Base URL

The base URL for API v2 is: https://[your-account-subdomain].bossdesk.io/api/v2

All API v2 requests should use this base URL as the prefix.
Example: To get an article list, make a GET request to: https://mycompany.bossdesk.io/api/v2/articles

Request headers

You must set the following Authorization and Content-Type headers with every request:

Authorization: Token token="your API key"
Content-Type: application/json

Response codes

Response code	Returned when
200 OK	Successful GET request
201 Created	Resource has been successfully created
204 No Content	Resource has been successfully updated
400 Bad Request	Request is erroneous (e.g. a required parameter was not provided)
401 Unauthorized	Failed API authorization
402 Payment Required	Failed request due to account expiration or subscription plan limits (e.g. no API access or no CMDB access)
403 Forbidden	No access to a resource (e.g. makes a user list request but has no user list permission)
404 Not Found	Requested resource was not found
409 Conflict	Edit conflict between multiple updates (e.g two agents updating the same Ticket that would result in one overwriting the changes of the other)
422 Unprocessable Entity	Request was fine but failed because of validation errors (e.g. the request tried to create a new user with a username that already exists)

Other things to keep in mind

When a parameter is required, it is marked as "REQUIRED FIELD". All other fields are optional.

Using the API

Article Categories

Thing	Value
URL	/article_categories
Method	GET
Response	Array of Article Categories
Pagination	Yes
Search	No

Example response:

[
  {
    "id": 1329,
    "friendly_id": 3,
    "name": "New Employee Setup"
  },
  {
    "id": 1330,
    "friendly_id": 4,
    "name": "Workstation Setup"
  }
]

Create Article Category

Thing	Value
URL	/article_categories
Method	POST
Response	Article Category

Example parameters:

{
  "article_category": {
    "name": "Onboarding Process" // REQUIRED
  }
}

Example successful response is 201 Created:

{
  "id": 1332,
  "friendly_id": 5,
  "name": "Onboarding Process"
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "name": ["can't be blank"]
  }
}

Articles

Retrieving the Article list

Thing	Value
URL	/articles
Method	GET
Response	Array of Articles
Pagination	Yes
Search	Yes

Example response:

[
  {
    "id": 35938,
    "friendly_id": 25,
    "title": "Setting up an email account",
    "status": "published",
    "visibility": "for_all",
    "group_ids": [],
    "updated_at": "2022-09-25T20:05:04.795Z",
    "category": {
      "id": 1329,
      "friendly_id": 3,
      "name": "New Employee Setup"
    }
  }
]

In addition to usual attribute-based filtering, article search also allows usage of these additional filters:

simple_search - this filter does a natural-language search on article title and text. It is an AND-based search, which means it will search for articles that contain all of the provided words. Example usage: /api/v2/articles?q[simple_search]=some+search+words.
wide_search - this filter does a natural-language search on article title and text. It is an OR-based search, which means it will search for articles that contain any of the provided words. Example usage: /api/v2/articles?q[wide_search]=some+search+words.

Retrieving one Article

Thing	Value
URL	/articles/:friendly_id
Method	GET
Successful response	Article

Example response:

{
  "id": 35938,
  "friendly_id": 25,
  "title": "Setting up an email account",
  "text": "<p>Log in to email.example.org. Go to <b>Settings</b> and then add a new email account.</p>",
  "status": "published",
  "visibility": "for_all",
  "group_ids": [],
  "updated_at": "2023-01-03T10:50:27.390Z",
  "category": {
    "id": 1329,
    "friendly_id": 3,
    "name": "New Employee Setup"
  },
  "attachments": [
    {
      "id": 9239332,
      "description": "Detailed instructions for navigating the settings of the email server",
      "size": 1352994,
      "name": "email server instructions.pdf"
    },
  ]
}

Create Article

Thing	Value
URL	/articles
Method	POST
Successful response	Article

Example parameters:

{
  "article":{
    "title": "Setting up an email account", // REQUIRED
    "status": "draft", // REQUIRED
    "text": "<p>Log in to email.example.org. Go to <b>Settings</b> and then add a new email account.</p>", // REQUIRED
    "visibility": "for_all", // REQUIRED
    "group_ids": [],
    "category_id": 1329, // REQUIRED
  }
}

Example successful response is 201 Created:

{
  "id": 35938,
  "friendly_id": 25,
  "title": "Setting up an email account",
  "text": "<p>Log in to email.example.org. Go to <b>Settings</b> and then add a new email account.</p>",
  "status": "draft",
  "visibility": "for_all",
  "group_ids": [],
  "updated_at": "2023-01-03T10:50:27.390Z",
  "category": {
    "id": 1329,
    "friendly_id": 3,
    "name": "New Employee Setup"
  },
  "attachments": []
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "text": ["can't be blank"]
  }
}

Update Article

Thing	Value
URL	/articles/:friendly_id
Method	PUT
Successful response	Article

Example parameters:

{
  "article":{
    "title": "Updated Setting up an email account",
    "status": "published",
    "text": "<p>Log in to email.example.org. Go to <b>Settings</b> and then add a new email account.</p>",
    "visibility": "for_all",
    "group_ids": [],
    "category_id": 1329
  }
}

Example successful response is 200 OK:

{
  "id": 35938,
  "friendly_id": 25,
  "title": "Updated Setting up an email account",
  "text": "<p>Log in to email.example.org. Go to <b>Settings</b> and then add a new email account.</p>",
  "status": "published",
  "visibility": "for_all",
  "group_ids": [],
  "updated_at": "2023-01-03T10:50:27.390Z",
  "category": {
    "id": 1329,
    "friendly_id": 3,
    "name": "New Employee Setup"
  },
  "attachments": []
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "text": ["can't be blank"]
  }
}

Attachments

New Attachment request

Thing	Value
URL	/articles/:friendly_id/attachments/new
Method	GET
Response	Attachment details or error

Example request:

{
  "attachment": {
    "filename": "image.jpg", // REQUIRED
    "byte_size": "204800", // REQUIRED
    "checksum": "d41d8cd98f00b204e9800998ecf8427e", // REQUIRED
    "content_type": "image/jpeg" // REQUIRED
  }
}

Example successful response:

{
  "put_url": "https://example-bucket.s3.amazonaws.com/uploads/tmp/example-file.jpg",
  "signed_id": "12345abcdef67890"
}

Extract the signed_id field and use it in the Creating an Attachment step.

To direct-upload the Attachment, construct a HTTP PUT request to "put_url" and add "attachment" and the desired file as multipart data.

For S3 upload:

When the request is valid, you'll be responded with an 200 status.

When the request is invalid, you'll be responded with an XML document that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Code>SignatureDoesNotMatch</Code>
    <Message>The request signature we calculated does not match the signature you provided. Check your key and signing method.</Message>
    <AWSAccessKeyId>SAMPLE_AWSAccessKeyId</AWSAccessKeyId>
    <StringToSign>SAMPLE_StringToSign</StringToSign>
    <SignatureProvided>SAMPLE_SignatureProvided</SignatureProvided>
    <StringToSignBytes>41 57 53 34 2d 48 4d 41 43 2d 53 48 41 32 35 36 0a 32 30 32 34 31 32 31 39 54 31 35 31 35 30 32 5a 0a 32 30 32 34 31 32 31 39 2f 75 73 2d 65 61 73 74 2d 31 2f 73 33 2f 61 77 73 34 5f 72 65 71 75 65 73 74 0a 65 63 35 36 36 30 34 37 38 63 35 34 31 63 39 61 34 31 63 61 30 34 38 36 30 61 39 64 35 63 64 65 65 32 31 63 64 38 38 63 36 62 32 32 37 64 62 35 63 34 64 35 34 31 37 38 37 62 37 38 65 62 64 63</StringToSignBytes>
    <CanonicalRequest>PUT
/3mfz9tlfl8ym2oiij2clwdibbaj5
X-Amz-Algorithm=AWS4-HMAC-SHA256&amp;X-Amz-Credential=SAMPLE_AWSAccessKeyId%2Fus-east-1%2Fs3%2Faws4_request&amp;X-Amz-Date=20241219T151502Z&amp;X-Amz-Expires=600&amp;X-Amz-SignedHeaders=content-length%3Bcontent-md5%3Bcontent-type%3Bhost
content-length:SAMPLE_length
content-md5:SAMPLE_md5
content-type:
host:bossdesk-bucket.s3.amazonaws.com

content-length;content-md5;content-type;host
UNSIGNED-PAYLOAD</CanonicalRequest>
    <CanonicalRequestBytes>50 55 54 0a 2f 33 6d 66 7a 39 74 6c 66 6c 38 79 6d 32 6f 69 69 6a 32 63 6c 77 64 69 62 62 61 6a 35 0a 58 2d 41 6d 7a 2d 41 6c 67 6f 72 69 74 68 6d 3d 41 57 53 34 2d 48 4d 41 43 2d 53 48 41 32 35 36 26 58 2d 41 6d 7a 2d 43 72 65 64 65 6e 74 69 61 6c 3d 41 4b 49 41 55 55 50 49 34 5a 56 5a 37 51 48 58 4b 47 56 48 25 32 46 32 30 32 34 31 32 31 39 25 32 46 75 73 2d 65 61 73 74 2d 31 25 32 46 73 33 25 32 46 61 77 73 34 5f 72 65 71 75 65 73 74 26 58 2d 41 6d 7a 2d 44 61 74 65 3d 32 30 32 34 31 32 31 39 54 31 35 31 35 30 32 5a 26 58 2d 41 6d 7a 2d 45 78 70 69 72 65 73 3d 36 30 30 26 58 2d 41 6d 7a 2d 53 69 67 6e 65 64 48 65 61 64 65 72 73 3d 63 6f 6e 74 65 6e 74 2d 6c 65 6e 67 74 68 25 33 42 63 6f 6e 74 65 6e 74 2d 6d 64 35 25 33 42 63 6f 6e 74 65 6e 74 2d 74 79 70 65 25 33 42 68 6f 73 74 0a 63 6f 6e 74 65 6e 74 2d 6c 65 6e 67 74 68 3a 38 39 33 30 37 34 0a 63 6f 6e 74 65 6e 74 2d 6d 64 35 3a 38 4d 78 63 52 74 73 6e 64 71 57 65 2b 42 65 33 4b 6e 58 6b 38 77 3d 3d 0a 63 6f 6e 74 65 6e 74 2d 74 79 70 65 3a 0a 68 6f 73 74 3a 61 77 73 2d 62 6f 73 73 64 65 73 6b 2d 74 65 73 74 2e 73 33 2e 61 6d 61 7a 6f 6e 61 77 73 2e 63 6f 6d 0a 0a 63 6f 6e 74 65 6e 74 2d 6c 65 6e 67 74 68 3b 63 6f 6e 74 65 6e 74 2d 6d 64 35 3b 63 6f 6e 74 65 6e 74 2d 74 79 70 65 3b 68 6f 73 74 0a 55 4e 53 49 47 4e 45 44 2d 50 41 59 4c 4f 41 44</CanonicalRequestBytes>
    <RequestId>5BW2HHZW20DSFBKS</RequestId>
    <HostId>CFRb7tTLozqYH1HkvlxF+PFecGxQUumMbVgG9HnkRlCIJ7ct2OT8IeHlJrLvVmaI/BywCJkpYcw=</HostId>
</Error>

For On-prem upload:

When the request is valid, you'll be responded with an 204 status.

When the request is invalid, you'll be responded with an 403 status.

Creating an Attachment

Thing	Value
URL	/articles/:friendly_id/attachments
Method	POST
Response	Attachment or error list

{
  "attachment": {
    "description": "Uploaded from mobile device", // REQUIRED
    "signed_id": "12345abcdef67890" // REQUIRED
  }
}

Example successful response:

{
  "id": 101,
  "description": "Sample Attachment",
  "size": 73604,
  "created_at": "2024-09-12T08:47:00.032Z",
  "updated_at": "2024-09-25T14:06:06.881Z",
  "name": "image.jpg",
  "secure_url": "https://example-bucket.s3.amazonaws.com/uploads/sample-image.jpg",
  "created_by": {
    "id": 202,
    "friendly_id": 303,
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe"
  },
  "secure_url_expire_time_in_mins": 10
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "base": "Error creating the Attachment"
  }
}

Retrive Article Attachment Details

Thing	Value
URL	/articles/:friendly_id/attachments/:id
Method	GET
Response	Attachment or error list

Example successful response:

{
  "id": 101,
  "description": "Update description",
  "size": 73604,
  "created_at": "2024-09-12T08:47:00.032Z",
  "updated_at": "2024-09-25T14:06:06.881Z",
  "name": "image.jpg",
  "secure_url": "https://example-bucket.s3.amazonaws.com/uploads/sample-image.jpg",
  "created_by": {
    "id": 202,
    "friendly_id": 303,
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe"
  },
  "secure_url_expire_time_in_mins": 10
}

Updating Article Attachment Details

Thing	Value
URL	/articles/:friendly_id/attachments/:id
Method	PUT
Response	Attachment or error list

Example parameters:

{
  "attachment": {
    "description": "Update description" // REQUIRED
  }
}

Example successful response with 200:

{
  "id": 101,
  "description": "Update description",
  "size": 73604,
  "created_at": "2024-09-12T08:47:00.032Z",
  "updated_at": "2024-09-25T14:06:06.881Z",
  "name": "image.jpg",
  "secure_url": "https://example-bucket.s3.amazonaws.com/uploads/sample-image.jpg",
  "created_by": {
    "id": 202,
    "friendly_id": 303,
    "first_name": "John",
    "last_name": "Doe",
    "username": "john.doe"
  },
  "secure_url_expire_time_in_mins": 10
}

Example unsuccessful response with validation errors:

{
  "errors": {
    "description": ["is invalid"]
  }
}

Pagination

By default 15 items are returned. Here is how you can traverse the pages.

Page

You can specify the next page by including the page parameter like this:

https://domain/api/v2/articles?page=2

The page param is 1-based.

Per page

To specify how many items per page you want use the per_page parameter like this:

https://domain/api/v2/articles?per_page=20

The default is 15 with a minimum of 1 and a maximum of 30.

Search

You may want to filter results on certain listings that support it (articles, article categories etc). You can use Ransack and its predicates to achieve that.

For example, if you want to search for users whose last name is Foley, you append the "q" parameter and the "eq" predicate to the query:

https://domain/api/v2/articles?q[title_eq]=Foley

You can also search using multiple filters:

https://domain/api/v2/articles?q[visibility_eq]=Foley&q[title_cont]=Axel

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

General information

API URL

V2 Base URL

Request headers

Response codes

Other things to keep in mind

Using the API

Article Categories

Retrieving the Article Category list

Create Article Category

Articles

Retrieving the Article list

Retrieving one Article

Create Article

Update Article

Attachments

New Attachment request

For S3 upload:

For On-prem upload:

Creating an Attachment

Retrive Article Attachment Details

Updating Article Attachment Details

Pagination

Page

Per page

Search