The Knowledge Management API provides endpoints for searching, viewing, and fetching lists of the most-viewed and featured knowledge articles.

You can only use this API when the Knowledge API (sn_km_api) plugin is activated. The Knowledge Management REST API was originally released in Orlando using the Knowledge API app available in the ServiceNow Store.

Note: The Knowledge Management REST API is publicly accessible and makes any knowledge base that is publicly accessible available to all users, including unauthenticated users. For version 1.0.1 and later, the API was made editable, allowing admins to configure each endpoint to disallow unauthenticated access by selecting the Requires Authentication flag on the Scripted REST Service Security tab associated with the API.

To enable other domains to use Knowledge Management REST API endpoints, define a Cross-Origin Resource Sharing (CORS) rule. For more information, see Define a CORS rule.

To view an article from the scoped knowledge base using this REST API, allow the sn_km_api scope read access from the requesting scope in the Restricted Caller Access Privileges [sys_restricted_caller_access] table. For more information, see Define cross-scope access to an application resource.

By default, this API has a rate limit of 500 per hour for unauthenticated and snc_external users. For more information about rate limiting, see Inbound REST API rate limiting.

Knowledge Management - GET /knowledge/articles

Returns a list of knowledge base (KB) articles which can be searched and filtered using various parameters.

URL format

Versioned URL: /api/sn_km_api/{api_version}/knowledge/articles

Default URL: /api/sn_km_api/knowledge/articles

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 3. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 5. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Example: cURL request

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/articles?query=Windows&limit=2&fields=short_description&fields=sys_class_name" \
--request GET \
--header "Accept:application/xml" \
--user "username":"password"
{
  "result": {
    "meta": {
      "start": 0,
      "end": 2,
      "fields": "short_description,sys_class_name",
      "query": "Windows",
      "filter": "",
      "kb": "",
      "language": "en",
      "count": 19,
      "ts_query_id": "7976f36129c30410f877796e70786991",
      "status": {
        "code": 200
      }
    },
    "articles": [
      {
        "link": "?sys_kb_id=9e528db1474321009db4b5b08b9a71a6&id=kb_article_view&sysparm_rank=1&sysparm_tsqueryId=7976f36129c30410f877796e70786991",
        "rank": 1,
        "id": "kb_knowledge:9e528db1474321009db4b5b08b9a71a6",
        "title": "Windows: Should I upgrade to Windows 8.x?",
        "snippet": "    Should I upgrade to <B>Windows</B> 8.x? <B>Windows</B> 8.x is designed for using touch, mouse, and keyboard the <B>Windows</B> Store and access apps such as Calendar, Mail, and Messaging. By most accounts, <B>Windows</B> boot times, smaller memory footprint, and more free memory for the programs you run. <B>Windows</B>",
        "score": 14.869,
        "number": "KB0000020",
        "fields": {
          "short_description": {
            "display_value": "Windows: Should I upgrade to Windows 8.x?\n\t\t",
            "name": "short_description",
            "label": "Short description",
            "type": "string",
            "value": "Windows: Should I upgrade to Windows 8.x?\n\t\t"
          },
          "sys_class_name": {
            "display_value": "Knowledge",
            "name": "sys_class_name",
            "label": "Class",
            "type": "sys_class_name",
            "value": "kb_knowledge"
          }
        }
      },
      {
        "link": "?sys_kb_id=3b07857187032100deddb882a2e3ec20&id=kb_article_view&sysparm_rank=2&sysparm_tsqueryId=7976f36129c30410f877796e70786991",
        "rank": 2,
        "id": "kb_knowledge:3b07857187032100deddb882a2e3ec20",
        "title": "What is the Windows key?",
        "snippet": "What is the <B>Windows</B> key? The <B>Windows</B> key is a standard key on most keyboards on computers built to use a <B>Windows</B> operating system. It is labeled with a <B>Windows</B> logo, and is usually placed between on the right side as well. Pressing Win (the <B>Windows</B> key) on its own will do the following: <B>Windows</B> 8.x: Toggle",
        "score": 13.4826,
        "number": "KB0000017",
        "fields": {
          "short_description": {
            "display_value": "What is the Windows key?\t\t",
            "name": "short_description",
            "label": "Short description",
            "type": "string",
            "value": "What is the Windows key?\t\t"
          },
          "sys_class_name": {
            "display_value": "Knowledge",
            "name": "sys_class_name",
            "label": "Class",
            "type": "sys_class_name",
            "value": "kb_knowledge"
          }
        }
      }
    ]
  }
}

Knowledge Management - GET /knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

Returns a knowledge article attachment as a file.

URL format

Versioned URL: /api/sn_km_api/{api_version}/knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

Default URL: /api/sn_km_api/knowledge/articles/{article_sys_id}/attachments/{attachment_sys_id}

Supported request parameters

Table 7. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
article_sys_id Sys_id of the knowledge article with the attachment you intend to retrieve. Located in the Knowledge Bases [kb_knowledge] table.

Data type: String
attachment_sys_id Sys_id of record to which the attachment belongs.

Data type: String
Table 8. Query parameters
Name Description
None
Table 9. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 11. Response headers
Header Description
Content-Type The content type of the response, for example, image/gif or */*.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters

Name Description
File is returned as a response.

Example: Sample cURL request

curl "https://instance.service-now.com/api/sn_km_api/knowledge/articles/0b48fd75474321009db4b5b08b9a71c2/attachments/fedf5614294f4010f877796e70786956" \
--request GET \
--header "Accept:*/*" \
--user "username":"password"
Binary response not shown (file is returned as a response).

Knowledge Management - GET /knowledge/articles/{id}

Returns specific knowledge article content and its field values.

URL format

Versioned URL: /api/sn_km_api/{api_version}/knowledge/articles/{id}

Default URL: /api/sn_km_api/knowledge/articles/{id}

Supported request parameters

Table 19. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
id Sys_id or knowledge base (KB) number of a knowledge article in the Knowledge [kb_knowledge] table.

Data type: String
Table 21. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 22. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 23. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 24. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Example: cURL request

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/articles/0b48fd75474321009db4b5b08b9a71c2?search_id=spam&search_rank=26.426" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  "result": {
    "content": "<p><span style=\"font-size: 18pt;\"><strong>How to Deal with Spam</strong></span></p>\r\n<p>Spam has increasingly become a problem on the Internet. While every Internet user receives some spam, email  addresses posted to web sites or in newsgroups and chat rooms attract the most spam.</p>\r\n<p>To reduce the amount of spam you receive:</p>\r\n<p>
    "template": false,
    "number": "KB0000011",
    "sys_id": "0b48fd75474321009db4b5b08b9a71c2",
    "short_description": "How to Deal with Spam",
    "display_attachments": true,
    "attachments": [
      {
        "sys_id": "dc27ae18294f4010f877796e707869c8",
        "file_name": "image.jpg",
        "size_bytes": "66792",
        "state": "available_conditionally"
      },
      {
        "sys_id": "fedf5614294f4010f877796e70786956",
        "file_name": "attachment.txt",
        "size_bytes": "75",
        "state": "available_conditionally"
      }
    ],
    "embedded_content": []
  }
}

Example: Sample cURL request (update_view)

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/KB0000020?update_view=' \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  "result": {
    "content": "<p> </p>\r\n<p> </p>\r\n<p><strong><span style=\"font-size: 18pt;\">Should I upgrade to Windows 8.x?</span></strong></p>\r\n<p>Windows 8.x is designed for using touch, mouse, and keyboard together, on hardware ranging from touch-enabled tablets and laptops to PCs and all-in-one computers...(intentionally truncated)</p>",
    "template": false,
    "number": "KB0000020",
    "sys_id": "9e528db1474321009db4b5b08b9a71a6",
    "short_description": "Windows: Should I upgrade to Windows 8.x?\t\t",
    "display_attachments": true,
    "attachments": [],
    "embedded_content": []
  }
}

Knowledge Management - GET knowledge/articles/most_viewed

Returns a list of knowledge articles prioritized by most-viewed.

URL format

Versioned URL: /api/sn_km_api/{api_version}/knowledge/articles/most_viewed

Default URL: /api/sn_km_api/knowledge/articles/most_viewed

Supported request parameters

Table 25. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 27. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 28. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 29. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 30. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or have not been passed.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Example: cURL request

curl "https://instance.servicenow.com/api/sn_km_api/knowledge/articles/most_viewed?limit=5" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
{
  "result": {
    "meta": {
      "start": 0,
      "end": 5,
      "fields": "",
      "query": "",
      "filter": "workflow_state=published^valid_to>=javascript:gs.beginningOfToday()^active=true^sys_class_name!=kb_knowledge_block^sys_view_count>0^ORDERBYDESCsys_view_count^ORDERBYshort_description",
      "kb": "",
      "count": 2,
      "status": {
        "code": 200
      },
      "language": "en"
    },
    "articles": [
      {
        "link": "?id=kb_article_view&sys_kb_id=0b48fd75474321009db4b5b08b9a71c2",
        "id": "kb_knowledge:0b48fd75474321009db4b5b08b9a71c2",
        "title": "How to Deal with Spam",
        "snippet": "How to Deal with Spam Spam has increasingly become a problem on the Internet. While every Internet user receives some spam, email addresses posted to web sites or in newsgroups and chat rooms attract the most spam. To reduce the amount of spam you receive: Don't reply to spam Be careful releasing your email address, and know how it will be used ",
        "score": 7,
        "tags": [],
        "number": "KB0000011"
      },
      {
        "link": "?id=kb_article_view&sys_kb_id=c85cd2519f77230088aebde8132e70c2",
        "id": "kb_knowledge:c85cd2519f77230088aebde8132e70c2",
        "title": "Microsoft Outlook Issues",
        "snippet": "Microsoft Outlook Issues This article explains how to use automatic replies in Outlook 2010 for Exchange accounts. Setting Up Automatic Replies Click the File tab. Click Automatic Replies. Select Send automatic replies. If desired, select the Only send during this time range check box to schedule when your out of office replies are active. If yo",
        "score": 6,
        "tags": [],
        "number": "KB99999999"
      }
    ]
  }
}