The External Content Ingestion API provides endpoints that enable ingestion of content from sources outside of your ServiceNow® instance into the ServiceNow® AI Search application's index.

External Content Ingestion API – DELETE /ais/external_content/deleteByQuery/{schema_table_name}

Deletes all external documents that match the specified query from the AI Search index.

URL format

Versioned URL: /api/now/{api_version}/ais/external_content/deleteByQuery/{schema_table_name}?query={query}

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
schema_table_name

The name of the external content schema table that defines the schema for the indexed documents to delete. For example, u_ext_content.

Data type: String
Table 2. Query parameters
Name Description
query

A valid URL-escaped query for the schema table specified by schema_table_name. For example, title=Introduction to query for documents whose title is Introduction.

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. Only supports 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.
400 Bad Request. A bad request type or malformed request was detected.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
error

Object describing the error encountered during processing of the request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail

Details of the error encountered during processing of the request.

Data type: String
error.message

Message for the error encountered during processing of the request.

Data type: String
result

Result from a successfully processed request.

Data type: String
status

Status of an unsuccessful request.

Valid values:
  • failure

Data type: String

Example: cURL request

Delete documents with title field values Introduction and Report for 31 October 2020 from the u_ext_content schema table.

curl "https://instance.service-now.com/api/now/v2/ais/external_content/deleteByQuery/u_ext_content?query=title%3DIntroduction%20OR%20title%3DReport%20for%2031%20October%202020" \
--request DELETE \
--user "username":"password" \
--header "Accept: application/json"
{
  "result": "Delete By Query Successfully Executed"
}

External Content Ingestion API – DELETE /ais/external_content/deleteDocument/{schema_table_name}/{document_id}

Deletes the external document with a specified unique identifier from the AI Search index.

URL format

Versioned URL: /api/now/{api_version}/ais/external_content/deleteDocument/{schema_table_name}/{document_id}

Supported request parameters

Table 7. Path parameters
Parameter 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
document_id

The unique identifier for the external document to delete. For example, ADMIN-2027858531-16.

Data type: string
schema_table_name

The name of the external content schema table that defines the schema for the indexed document to delete. For example, u_ext_content.

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. Only supports application/json.
Table 11. 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 12. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Element Description
error

Object describing the error encountered during processing of the request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail

Details of the error encountered during processing of the request.

Data type: String
error.message

Message for the error encountered during processing of the request.

Data type: String
result

Result from a successfully processed request.

Data type: String
status

Status of an unsuccessful request.

Valid values:
  • failure

Data type: String

Example: cURL request

Delete the document with identifier ADMIN-2587918521-27 from the u_ext_content schema table.

curl 'https://instance.service-now.com/api/now/v2/ais/external_content/deleteDocument/u_ext_content/ADMIN-2587918521-27' \
--request DELETE \
--user 'username':'password' \
--header 'Accept: application/json'
{
  "result":"Document removed"
}

External Content Ingestion API – POST /ais/external_content/ingestDocument/{schema_table_name}

Sends a list of external documents to the AI Search ingestion batcher for indexing. After indexing completes, content from the ingested documents becomes searchable.

You can use this endpoint to feed external documents with text content and metadata.

If you need to associate searchable binary content and metadata with an external document, follow these steps:
  1. Store the binary content in AI Search using the POST /ais/external_content/storeContent endpoint. Record the value of the result response body parameter.
  2. Send the external document to AI Search using this endpoint. Set the document's content_pointer request body parameter to match the recorded result response body parameter value.
During ingestion, AI Search parses the binary content and adds its searchable content to the indexed record that represents the external document. Parsing removes the stored content object.

URL format

Versioned URL: /api/now/{api_version}/ais/external_content/ingestDocument/{schema_table_name}

Supported request parameters

Table 13. Path parameters
Parameter 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
schema_table_name

The name of the external content schema table that defines the schema for external documents in the request. For example, u_ext_content.

Data type: String
Table 14. Query parameters
Name Description
None
Table 15. Request body parameters (XML or JSON)
Element Description
[array]

Required. Unnamed array of objects in which each object represents an external document to ingest for indexing.

Data type: Array

[
  {
    "content_pointer": "String",
    "document_id": "String",
    "principals": {Object},
    "properties": {Object}
  }
]
[array].content_pointer
Identifier for an instance of binary content stored using the POST /ais/external_content/storeContent endpoint. During ingestion, AI Search parses the binary content and adds its searchable content to the indexed record that represents the external document. Parsing removes the stored content object.
Note: This identifier should match the result response body element returned by the storeContent endpoint.

Data type: String
[array].document_id

Required. Unique identifier for the external document in the external content schema table specified by the schema_table_name path parameter.

Note: When you ingest a document, it overwrites any existing document in the same external content schema table that has the same document_id. If two or more documents in the same ingestion request have the same document_id, the request fails.

Data type: String
[array].principals
Object containing key-value pairs that describe the external document's access permissions for externally defined security principals (users and groups).
Note:

If you omit this parameter for a document, the request succeeds, but AI Search rejects the document with the ingestion feedback message The principal of the document is missing.

If this parameter object does not include any key-value pairs that grant access to a document, the request succeeds, but AI Search rejects the document with the ingestion feedback message The principal of the document is invalid.

Data type: Object

"principals": {
  "everyone": Boolean,
  "groups.deny": [Array],
  "groups.read": [Array],
  "none": Boolean,
  "users.deny": [Array],
  "users.read": [Array]
}

Versions supported: Available starting in v2 of the API.
[array].principals.everyone
Flag that indicates whether access to the external document is allowed for all users. When this parameter is set to true, all ServiceNow AI Platform users can view the indexed record created from the document.
Note: If you set both this parameter and [array].principals.none to true for a document, the request succeeds, but AI Search rejects the document with ingestion feedback message The principal of the document is invalid. You can only set one of these two parameters to true in a request.
Valid values:
  • true: Allow access to the document for all users. AI Search ignores all [array].principals.groups.* and [array].principals.users.* parameter settings for the document.
  • false: Do not allow all users to access the external document. Users can only access the document if [array].principals.none is set to false and if allowed by the interaction of their user mappings and the [array].principals.groups.* and [array].principals.users.* parameters.

Data type: Boolean

Default: true

Versions supported: Available starting in v2 of the API.
[array].principals.groups.deny

Array of strings where each string is the name of an externally defined group that is denied access to the external document. ServiceNow AI Platform users mapped to any of these external groups cannot view the indexed search result record created from the document.

If either [array].principals.everyone or [array].principals.none is set to true, this parameter has no effect.

This parameter takes precedence over [array].principals.groups.read. If the same user is mapped to external groups with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.

By default, [array].principals.users.read takes precedence over this parameter. To reverse this precedence order for an indexed source, see Change the precedence of user read and group deny permissions for an external content indexed source..

Data type: Array

Values can be in any format, depending on the names of the externally defined groups specified. Examples include:

"groups.deny": [
  "hr-admin",
  "legal"
]

Versions supported: Available starting in v2 of the API.
[array].principals.groups.read

Array of strings where each string is the name of an externally defined group that is allowed to access the external document. ServiceNow AI Platform users mapped to any of these external groups can view the indexed search result record created from the document.

If either [array].principals.everyone or [array].principals.none is set to true, this parameter has no effect.

[array].principals.groups.deny takes precedence over this parameter. If the same user is mapped to external groups with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.

Data type: Array

Values can be in any format, depending on the names of the externally defined groups specified. Examples include:

"groups.read": [
  "devops",
  "it",
  "report-admins"
]

Versions supported: Available starting in v2 of the API.
[array].principals.none
Boolean option indicating whether access to the external document is denied for all users. When this parameter is set to true, only ServiceNow AI Platform users with the ais_high_security_admin elevated privilege role can view the indexed record created from the document.
Note: If you set both this parameter and [array].principals.everyone to true for a document, AI Search rejects the document during ingestion with error message The principal of the document is invalid. You can only set one of these two parameters to true in a request.
Valid values:
  • true: Deny access to the document for all users except those with the ais_high_security_admin elevated privilege role. AI Search ignores all [array].principals.groups.* and [array].principals.users.* parameter settings for the document.
  • false: Do not deny access to the document for all users. Users can access the document if [array].principals.everyone is set to true, or if allowed by the interaction of their user mappings and the [array].principals.groups.read and [array].principals.users.read parameters.

Data type: Boolean

Default: false

Versions supported: Available starting in v2 of the API.
[array].principals.users.deny

Array of strings where each string is the name of an externally defined user that is denied access to the external document. ServiceNow AI Platform users mapped to any of these external users cannot view the indexed search result record created from the document.

If either [array].principals.everyone or [array].principals.none is set to true, this parameter has no effect.

This parameter takes precedence over [array].principals.users.read. If the same user is mapped to external users with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.

Data type: Array

Values can be in any format, depending on the names of the externally defined users specified. Examples include:

"users.deny": [
  "ad\bow-ruggeri",
  "abel-tuter@sharepoint"
]

Versions supported: Available starting in v2 of the API.
[array].principals.users.read

Array of strings where each string is the name of an externally defined user that is allowed to access the external document. ServiceNow AI Platform users mapped to any of these external users can view the indexed search result record created from the document.

If either [array].principals.everyone or [array].principals.none is set to true, this parameter has no effect.

[array].principals.users.deny takes precedence over this parameter. If the same user is mapped to external users with both read and deny access permissions for a document, AI Search denies that user access to the indexed record.

By default, this parameter takes precedence over [array].principals.groups.deny. To reverse this precedence order for an indexed source, see Change the precedence of user read and group deny permissions for an external content indexed source..

Data type: Array

Values can be in any format, depending on the names of the externally defined users specified. Examples include:

"users.read": [
  "ad\abel-tuter",
  "beth-anglin@sharepoint"
]

Versions supported: Available starting in v2 of the API.
[array].properties

Object containing name-value pairs where each pair represents a field name and value to ingest for the document. All field names and values must be specified as strings.

After ingestion, these document field values are accessible through the indexed source defined for the external content schema table specified by the schema_table_name path parameter. Users can search for these field values in search sources derived from this indexed source.

Data type: Object

Field names can only contain lowercase letters and underscores. Values can include any characters. Value length is limited by the max_length attribute defined for the field in the external content schema table. Examples of field name-value pairs include:

"properties": {
  "creation_date": "2020-11-03 12:27:43",
  "file_size": "10285",
  "title": "Introduction",
  "url": "file:///myhost/reports/Introduction.pdf"
}

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 16. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Content-Type Data format of the request body. Only supports application/json.
Table 17. 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 18. Status codes
Status code Description
200 Successful. The request was successfully processed.
202 Partial Success. The request was processed. Some documents have ingestion feedback warning or error messages.
400 Bad Request. A bad request type or malformed request was detected.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name Description
error

Object describing the error encountered during processing of the request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail

Details of the error encountered during processing of the request.

Data type: String
error.message

Message for the error encountered during processing of the request.

Data type: String
result

JSON-formatted string representing the result object for the ingestion request.

Data type: String

"result": "{\"duration_in_ms\": Number, \"feedback\": [Array] }"
result.duration_in_ms

Time spent ingesting the external documents.

Data type: Number

Unit: Milliseconds
result.feedback

Array of objects in which each object represents feedback for a document ingested from the request body.

Data type: Array

"feedback": [
  {
    "document_id": "String",
    "messages": [Array]
  }
]
result.feedback.document_id

Unique identifier for the external document as specified in the request body.

Data type: String
result.feedback.messages

Array of unnamed objects in which each object represents an ingestion feedback message logged during indexing of the external document.

Data type: Array

"messages": [
  {
    "code": "String",
    "component": "String",
    "level": "String",
    "message": "String"
  }
]
result.feedback.messages.code

Code for an exception thrown by the indexing workflow component that logged the ingestion feedback message.

Data type: String
result.feedback.messages.component

Identifier for the indexing workflow component that logged the ingestion feedback message.

Data type: String
result.feedback.messages.level

Logging level for the ingestion feedback message.

Valid values:
  • ERROR
  • INFO
  • MINOR_ERROR
  • WARN

Data type: String
result.feedback.messages.message

Text logged for the ingestion feedback message.

Data type: String
status

Status of an unsuccessful request.

Valid values:
  • failure

Data type: String

Precedence order for principal permissions

The precedence order for [array].principals permissions depends on the value of the user_read_takes_precedence_over_group_deny attribute for the indexed source used to ingest an external document.
Attribute value Precedence order for principal permissions
true
From highest precedence to lowest:
  1. [array].principals.everyone, [array].principals.none
  2. [array].principals.users.deny
  3. [array].principals.users.read
  4. [array].principals.groups.deny
  5. [array].principals.groups.read
Note: This is the default attribute value for external content indexed sources.
false
From highest precedence to lowest:
  1. [array].principals.everyone, [array].principals.none
  2. [array].principals.users.deny, [array].principals.groups.deny
  3. [array].principals.users.read, [array].principals.groups.read
Note: For instructions on setting this attribute value, see Change the precedence of user read and group deny permissions for an external content indexed source.

Example: cURL request

Feed two external documents (with content pointers to binary content objects previously stored using the POST /ais/external_content/storeContent endpoint) for indexing into the u_ext_content schema table.

curl 'https://instance.servicenow.com/api/now/v2/ais/external_content/ingestDocument/u_ext_content' \
  --request POST \
  --user 'username':'password' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "document_id": "ADMIN-2027858531-16",
    "content_pointer": "749b52a1-baa8-4556-a4f3-00404c95e6a8",
    "properties": {
      "title": "Introduction",
      "url": "file:///myhost/reports/Introduction.pdf",
      "file_name": "Introduction.pdf",
      "file_size": "10285",
      "creation_date": "2020-11-01 12:27:43"
    },
    "principals": {
      "everyone": false,
      "groups.read": [
        "report-users",
        "report-admins"
      ],
      "users.deny": [
        "ad\abel-tuter"
      ]
    }
  },
  {
    "document_id": "ADMIN-2587918521-27",
    "content_pointer": "bd605435-268b-464f-a7c3-0c5ea894a5c2",
    "properties": {
      "title": "Report for 31 August 2020",
      "url": "file:///myhost/reports/Report-2020-08-31.pdf",
      "file_size": "27597",
      "creation_date": "2020-09-01 12:48:13"
    },
    "principals": {
      "everyone": false,
      "groups.read": [
        "report-users",
        "report-admins"
      ],
      "users.read": [
        "ad\beth-anglin"
      ]
    }
  }
]'
{
  "result":"{\"duration_in_ms\":3822,\"feedback\":[{\"messages\":[{\"level\":\"INFO\",\"message\":\"CREATED\",\"component\":\"init\"},{\"level\":\"INFO\",\"message\":\"OK\",\"component\":\"index-886de18e750030108b23bcd69cdc2dd3-indexer.index-886de18e750030108b23bcd69cdc2dd3-content-dispatcher\"},{\"level\":\"INFO\",\"message\":\"COMPLETED\",\"component\":\"sink.sink\"}],\"document_id\":\"ADMIN-2027858531-16\"},{\"messages\":[{\"level\":\"INFO\",\"message\":\"CREATED\",\"component\":\"init\"},{\"level\":\"WARN\",\"message\":\"field \\u0027text\\u0027 tokens exceed index.maxTokens\",\"code\":\"INDEX_ENGINE-32\",\"component\":\"ingestGlideDocument.standardAnalyzer\"},{\"level\":\"INFO\",\"message\":\"OK\",\"component\":\"index-886de18e750030108b23bcd69cdc2dd3-indexer.index-886de18e750030108b23bcd69cdc2dd3-content-dispatcher\"},{\"level\":\"INFO\",\"message\":\"COMPLETED\",\"component\":\"sink.sink\"}],\"document_id\":\"ADMIN-2587918521-27\"}]}"
}

External Content Ingestion API – POST ais/external_content/storeContent

Stores binary content as a content object in AI Search.

You can associate stored binary content with an external document by following these steps:
  1. Store the binary content using this endpoint. Record the value of the result response body parameter.
  2. Send the external document to AI Search using the POST /ais/external_content/ingestDocument/{schema_table_name} endpoint. Set the document's content_pointer request body parameter to match the recorded result response body parameter value.
During ingestion, AI Search parses the binary content and adds its searchable content to the indexed record that represents the external document. Parsing removes the stored content object.

URL format

Versioned URL: /api/now/{api_version}/ais/external_content/storeContent

Supported request parameters

Table 19. Path parameters
Parameter 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 20. Query parameters
Name Description
None
Table 21. Request body parameters
Element Description
[binary data] Required. Binary content to store as a content object in AI Search.

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. Only supports application/json.
Content-Type

Data format of the request body.

Valid values:
  • application/msword
  • application/octet-stream
  • application/pdf
  • application/vnd.ms-excel
  • application/vnd.ms-powerpoint
  • application/vnd.ms-powerpoint.presentation.macroenabled.12
  • application/vnd.openxmlformats-officedocument.presentationml.presentation
  • application/vnd.openxmlformats-officedocument.presentationml.template
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • application/vnd.openxmlformats-officedocument.wordprocessingml.template
  • text/html
  • text/plain
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.
400 Bad Request. A bad request type or malformed request was detected.
500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Element Description
error

Object describing the error encountered during processing of the request.

Data type: Object

"error": {
  "detail": "String",
  "message": "String"
}
error.detail

Details of the error encountered during processing of the request.

Data type: String
error.message

Message for the error encountered during processing of the request.

Data type: String
result

Identifier for the binary content object stored by successful request.

Data type: String

"result" : "91841766-2a5f-4c64-a20a-27ca485eca21"
Note: To attach the stored content to an ingested external document, specify this identifier as the content_pointer request body element for a request to the ingestDocument endpoint.
status

Status of an unsuccessful request.

Valid values:
  • failure

Data type: String

Example: cURL request

Store binary content for a PDF file as a content object.

curl 'https://instance.servicenow.com/api/now/v2/ais/external_content/storeContent' \
--request POST \
--user 'username':'password' \
--header 'Content-Type: application/pdf' \
--data-binary '@Report-2020-08-31.pdf'

The response body includes the unique identifier for the new content object.

{
  "result" : "fb439a4f-62ad-4dab-9654-5088d99a6ff9"
}