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": "internal",
    "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": "public",
    "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.

States

The following states are available:

Collection Fields

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

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

Sorting

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

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

List knowledge articles relevant for API user

List all knowledge articles that are linked to a service for which the the API user is the knowledge manager:

GET /knowledge_articles/managed_by_me

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",
  "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": "public",
  "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

created_at
Readonly datetime — The date and time at which the knowledge article was created.
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.
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.
locale
Optional string (max 5) — The language of the knowledge article.
service
Optional 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: being_prepared — The Status field is used to select the current status of the knowledge article. Valid values are:
  • new: New
  • internal: Internal
  • public: Public
  • archived: Archived
subject
Required string (max 255) — The Subject field is used to enter a short description of the knowledge article.
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.