Knowledge Articles API
- List knowledge articles
- Get a single knowledge article
- Create a knowledge article
- Update a knowledge article
- Fields
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:
/knowledge_articles/active
: List all active knowledge articles/knowledge_articles/archived
: List all archived knowledge articles/knowledge_articles/managed_by_me
: List all knowledge articles that are linked to a service for which the API user is the knowledge manager
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 Progressnot_validated
: Not Validatedvalidated
: Validatedarchived
: 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.