Knowledge Articles API

List knowledge articles

List all knowledge articles for an account:

GET /knowledge_articles

Response

Status: 200 OK
[
  {
    "id": 76,
    "sourceID": null,
    "subject": "How to connect a 2nd monitor to a desktop PC",
    "status": "not_validated",
    "service": {
      "id": 31,
      "name": "Personal Computing",
      "provider": {
        "id": 46,
        "name": "Widget Data Center",
        "account": {
          "id": "widget",
          "name": "Widget International"
        }
      },
      "localized_name": "Personal Computing"
    },
    "created_at": "2016-11-25T02:16:24-06:00",
    "updated_at": "2016-11-25T14:10:05-06:00"
  },
  {
    "id": 57,
    "sourceID": null,
    "subject": "How to book a conference room",
    "status": "validated",
    "key_contacts": true,
    "end_users": true,
    "service": {
      "id": 18,
      "name": "Conference Room",
      "provider": {
        "id": 46,
        "name": "Widget Data Center",
        "account": {
          "id": "widget",
          "name": "Widget International"
        }
      },
      "localized_name": "Conference Room"
    },
    "created_at": "2016-11-25T02:16:24-06:00",
    "updated_at": "2016-11-25T02:16:24-06:00"
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of knowledge articles.

Predefined Filters

The following predefined filters are available:

Collection Fields

By default the following fields will appear in collections of knowledge articles:

id sourceID subject status service created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Filtering

Filtering is available for the following fields:

id source sourceID subject status service created_by created_at updated_at

Sorting

By default a collection of knowledge articles is sorted descending by start_at.

The following fields are accepted by the ?sort= parameter:

id sourceID subject status created_at updated_at

Response

The response is similar to the response in List knowledge articles

Get a single knowledge article

GET /knowledge_articles/:id

Response

Status: 200 OK
{
  "id": 57,
  "locale": "en-US",
  "subject": "How to book a conference room",
  "keywords": "boardroom,meeting,appointment",
  "description": "This article describes how you can book a conference room using Outlook.",
  "instructions": "To book a conference room, follow the step below...",
  "created_at": "2016-11-25T02:16:24-06:00",
  "updated_at": "2016-11-25T02:16:24-06:00",
  "source": null,
  "sourceID": null,
  "status": "validated",
  "key_contacts": true,
  "end_users": true,
  "service": {
    "id": 18,
    "name": "Conference Room",
    "provider": {
      "id": 46,
      "name": "Widget Data Center",
      "account": {
        "id": "widget",
        "name": "Widget International"
      }
    },
    "localized_name": "Conference Room"
  }
}

The response contains these fields.

Create a knowledge article

POST /knowledge_articles

When creating a new knowledge article these fields are available.

Response

Status: 201 Created
{
  "instructions": "...",
  "...": "..."
}

The response contains all fields of the created knowledge article and is similar to the response in Get a single knowledge article

Update a knowledge article

PATCH /knowledge_articles/:id

When updating a knowledge article these fields are available.

Response

Status: 200 OK
{
  "instructions": "...",
  "...": "..."
}

The response contains all fields of the updated knowledge article and is similar to the response in Get a single knowledge article

Fields

archive_date
Optional date — The date until which the knowledge article will be active. The knowledge article will be archived at the beginning of this day. When the knowledge article is archived, its status will automatically be set to “Archived”.
attachments
Readonly aggregated Attachments
covered_specialists
Optional boolean, default: true — The Covered specialists box is checked when the knowledge article needs to be available to the people who are a member of the support team of one of the service instances that are selected in the Coverage section of an active SLA for the service that is linked to the article.
created_at
Readonly datetime — The date and time at which the knowledge article was created.
created_by
Readonly reference to Person — The Created by field is automatically set to the person who created the knowledge article.
custom_fields
Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related knowledge article template.
custom_fields_attachments
Writeonly attachments The attachments used in Custom fields.
description
Required text (max 64KB) — The Description field is used to describe the situation and/or environment in which the instructions of the knowledge article may be helpful.
description_attachments
Writeonly attachments The attachments used in the Description field.
end_users
Optional boolean, default: true — The End users box is checked when the knowledge article needs to be available to anyone who is covered by an active SLA for the service that is linked to the article.
id
Readonly integer — The unique ID of the knowledge article.
instructions
Required text (max 64KB) — The Instructions field is used to enter instructions for the service desk analysts, specialists and/or end users who are likely to look up the knowledge article to help them with their work or to resolve an issue.
instructions_attachments
Writeonly attachments The attachments used in the Instructions field.
internal_specialists
Optional boolean, default: true — The Internal specialists box is checked when the knowledge article needs to be available to the people who have the Specialist role of the account in which the article is registered.
key_contacts
Optional boolean, default: true — The Key contacts box is checked when the knowledge article needs to be available to the people who have the Key Contact role of the customer account of an active SLA for the service that is linked to the article.
keywords
Optional string (max 2048) — The Keywords field contains a comma-separated list of words that can be used to find the knowledge article using search.
locale
Optional string (max 5) — The language of the knowledge article.
service
Required reference to Service — The Service field is used to select the service for which the knowledge article is made available.
source
Optional string (max 30) — See source
sourceID
Optional string (max 128) — See source
status
Optional enum, default: not_validated — The Status field is used to select the current status of the knowledge article. Valid values are:
  • work_in_progress: Work In Progress
  • not_validated: Not Validated
  • validated: Validated
  • archived: Archived
subject
Required string (max 255) — The Subject field is used to enter a short description of the knowledge article.
template
Optional reference to Knowledge Article Template — The Template field is used to select the knowledge article template on which the knowledge article is based.
times_applied
Readonly integer — The number of requests to which the knowledge article is linked as the last applied knowledge article.
updated_at
Readonly datetime — The date and time of the last update of the knowledge article. If the knowledge article has no updates it contains the created_at value.
updated_by
Readonly reference to Person — The Updated by field is automatically set to the person who last updated the knowledge article. If the knowledge article has no updates it contains the created_by value.