External Content Ingestion API

Watch

Save as PDF

Share this page

Feedback

API implementation and reference

HomeYokohama API ReferenceAPI implementation and referenceAPI referenceREST API referenceExternal Content Ingestion API

Table of Contents

External Content Ingestion API

Release version:
Yokohama
Xanadu
Washington DC
Vancouver
UpdatedApr 22, 2025
14 minutes to read

Yokohama
API reference

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}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

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)

Search:


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}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

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

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)

Search:


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:

Store the binary content in AI Search using the POST /ais/external_content/storeContent endpoint. Record the value of the result response body parameter.
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}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

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

Search:

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

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.

Search:

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)

Search:


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: [array].principals.everyone, [array].principals.none [array].principals.users.deny [array].principals.users.read [array].principals.groups.deny [array].principals.groups.read Note: This is the default attribute value for external content indexed sources.
false	From highest precedence to lowest: [array].principals.everyone, [array].principals.none [array].principals.users.deny, [array].principals.groups.deny [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:

Store the binary content using this endpoint. Record the value of the result response body parameter.
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

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

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

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)

Search:


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"
}

External Content Ingestion API – DELETE /ais/external_content/deleteByQuery/{schema_table_name}
External Content Ingestion API – DELETE /ais/external_content/deleteDocument/{schema_table_name}/{document_id}
External Content Ingestion API – POST /ais/external_content/ingestDocument/{schema_table_name}
External Content Ingestion API – POST ais/external_content/storeContent

Was this topic helpful?

Yes No

Event Notification Management Open API

HR REST API

Event Notification Management Open API

HR REST API

Yokohama API Reference

Filters

Versions

Products

External Content Ingestion API

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

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Example: cURL request

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

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Example: cURL request

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

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Precedence order for principal permissions

Example: cURL request

External Content Ingestion API – POST ais/external_content/storeContent

URL format

Supported request parameters

Headers

Status codes

Response body parameters (JSON or XML)

Example: cURL request

On this page

Log in to get a better experience