External Content Ingestion API

</td></tr><tr><td>

\[array\].content\_pointer

</td><td><p>Identifier for an instance of binary content stored using the <a href="./">POST /ais/external_content/storeContent</a> 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.</p>
<p><strong>Note:</strong> This identifier should match the <strong>result</strong> response body element returned by the storeContent endpoint.</p>
<p>Data type: String</p></td></tr><tr><td>

\[array\].document\_id

</td><td><p>Required. Unique identifier for the external document in the external content schema table specified by the <strong>schema_table_name</strong> path parameter.</p>
<p><strong>Note:</strong> When you ingest a document, it overwrites any existing document in the same external content schema table that has the same <strong>document_id</strong>. If two or more documents in the same ingestion request have the same <strong>document_id</strong>, the request fails.</p>
<p>Data type: String</p></td></tr><tr><td>

\[array\].principals

</td><td><p>Object containing key-value pairs that describe the external document's access permissions for externally defined security principals (users and groups).</p>
<p><strong>Note:</strong></p>
<p>If you omit this parameter for a document, the request succeeds, but AI Search rejects the document with the ingestion feedback message <code>The principal of the document is missing</code>.</p>
<p>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 <code>The principal of the document is invalid</code>.</p>
<p>Data type: Object</p>
<p><code>"principals": {
  "everyone": Boolean,
  "groups.deny": [Array],
  "groups.read": [Array],
  "none": Boolean,
  "users.deny": [Array],
  "users.read": [Array]
}</code></p>
<p>Versions supported: Available starting in v2 of the API.</p></td></tr><tr><td>

\[array\].principals.everyone

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

\[array\].principals.groups.deny

</td><td><p>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.</p>
<p>If either <strong>[array].principals.everyone</strong> or <strong>[array].principals.none</strong> is set to <strong>true</strong>, this parameter has no effect.</p>
<p>This parameter takes precedence over <strong>[array].principals.groups.read</strong>. 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.</p>
<p>By default, <strong>[array].principals.users.read</strong> takes precedence over this parameter. To reverse this precedence order for an indexed source, see <a href="../../../platform-administration/ai-search/defining-access-perms-ext-docs-ais/">Change the precedence of user read and group deny permissions for an external content indexed source.</a>.</p>
<p>Data type: Array</p>
<p>Values can be in any format, depending on the names of the externally defined groups specified. Examples include:</p>
<p><code>"groups.deny": [
  "hr-admin",
  "legal"
]</code></p>
<p>Versions supported: Available starting in v2 of the API.</p></td></tr><tr><td>

\[array\].principals.groups.read

</td><td><p>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.</p>
<p>If either <strong>[array].principals.everyone</strong> or <strong>[array].principals.none</strong> is set to <strong>true</strong>, this parameter has no effect.</p>
<p><strong>[array].principals.groups.deny</strong> 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.</p>
<p>Data type: Array</p>
<p>Values can be in any format, depending on the names of the externally defined groups specified. Examples include:</p>
<p><code>"groups.read": [
  "devops",
  "it",
  "report-admins"
]</code></p>
<p>Versions supported: Available starting in v2 of the API.</p></td></tr><tr><td>

\[array\].principals.none

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

\[array\].principals.users.deny

</td><td><p>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.</p>
<p>If either <strong>[array].principals.everyone</strong> or <strong>[array].principals.none</strong> is set to <strong>true</strong>, this parameter has no effect.</p>
<p>This parameter takes precedence over <strong>[array].principals.users.read</strong>. 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.</p>
<p>Data type: Array</p>
<p>Values can be in any format, depending on the names of the externally defined users specified. Examples include:</p>
<p><code>"users.deny": [
  "ad\bow-ruggeri",
  "abel-tuter@sharepoint"
]</code></p>
<p>Versions supported: Available starting in v2 of the API.</p></td></tr><tr><td>

\[array\].principals.users.read

</td><td><p>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.</p>
<p>If either <strong>[array].principals.everyone</strong> or <strong>[array].principals.none</strong> is set to <strong>true</strong>, this parameter has no effect.</p>
<p><strong>[array].principals.users.deny</strong> 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.</p>
<p>By default, this parameter takes precedence over <strong>[array].principals.groups.deny</strong>. To reverse this precedence order for an indexed source, see <a href="../../../platform-administration/ai-search/defining-access-perms-ext-docs-ais/">Change the precedence of user read and group deny permissions for an external content indexed source.</a>.</p>
<p>Data type: Array</p>
<p>Values can be in any format, depending on the names of the externally defined users specified. Examples include:</p>
<p><code>"users.read": [
  "ad\abel-tuter",
  "beth-anglin@sharepoint"
]</code></p>
<p>Versions supported: Available starting in v2 of the API.</p></td></tr><tr><td>

\[array\].properties

</td><td><p>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.</p>
<p>After ingestion, these document field values are accessible through the indexed source defined for the external content schema table specified by the <strong>schema_table_name</strong> path parameter. Users can search for these field values in search sources derived from this indexed source.</p>
<p>Data type: Object</p>
<p>Field names can only contain lowercase letters and underscores. Values can include any characters. Value length is limited by the <strong>max_length</strong> attribute defined for the field in the external content schema table. Examples of field name-value pairs include:</p>
<p><code>"properties": {
  "creation_date": "2020-11-03 12:27:43",
  "file_size": "10285",
  "title": "Introduction",
  "url": "file:///myhost/reports/Introduction.pdf"
}</code></p></td></tr></tbody>
</table>

### 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](../rest-api-explorer/c_RESTAPI.md).

|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**.|

|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](../rest-api-explorer/c_RESTAPI.md).

|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\)

<table><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

error

</td><td>

Object describing the error encountered during processing of the request.

 Data type: Object

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

</td></tr><tr><td>

result.duration\_in\_ms

</td><td>

Time spent ingesting the external documents.

 Data type: Number

 Unit: Milliseconds

</td></tr><tr><td>

result.feedback

</td><td>

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

</td></tr><tr><td>

result.feedback.messages.code

</td><td>

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

 Data type: String

</td></tr><tr><td>

result.feedback.messages.component

</td><td>

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

 Data type: String

</td></tr><tr><td>

result.feedback.messages.level

</td><td><p>Logging level for the ingestion feedback message.</p>
<p>Valid values:</p>
<ul>
<li><strong>ERROR</strong></li>
<li><strong>INFO</strong></li>
<li><strong>MINOR_ERROR</strong></li>
<li><strong>WARN</strong></li>
</ul>
<p>Data type: String</p></td></tr><tr><td>

result.feedback.messages.message

</td><td>

Text logged for the ingestion feedback message.

 Data type: String

</td></tr><tr><td>

status

</td><td><p>Status of an unsuccessful request.</p>
<p>Valid values:</p>
<ul>
<li><strong>failure</strong></li>
</ul>
<p>Data type: String</p></td></tr></tbody>
</table>

### 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.

<table id="table_vlm_d2t_vpb"><thead><tr><th>

Attribute value

</th><th>

Precedence order for principal permissions

</th></tr></thead><tbody><tr><td>

true

</td><td><p>From highest precedence to lowest:</p>
<ol>
<li><strong>[array].principals.everyone</strong>, <strong>[array].principals.none</strong></li>
<li><strong>[array].principals.users.deny</strong></li>
<li><strong>[array].principals.users.read</strong></li>
<li><strong>[array].principals.groups.deny</strong></li>
<li><strong>[array].principals.groups.read</strong></li>
</ol>
<p><strong>Note:</strong> This is the default attribute value for external content indexed sources.</p></td></tr><tr><td>

false

</td><td><p>From highest precedence to lowest:</p>
<ol>
<li><strong>[array].principals.everyone</strong>, <strong>[array].principals.none</strong></li>
<li><strong>[array].principals.users.deny</strong>, <strong>[array].principals.groups.deny</strong></li>
<li><strong>[array].principals.users.read</strong>, <strong>[array].principals.groups.read</strong></li>
</ol>
<p><strong>Note:</strong> For instructions on setting this attribute value, see <a href="../../../platform-administration/ai-search/defining-access-perms-ext-docs-ais/">Change the precedence of user read and group deny permissions for an external content indexed source</a>.</p></td></tr></tbody>
</table>

### cURL request

Feed two external documents \(with content pointers to binary content objects previously stored using the [POST /ais/external\_content/storeContent](external-content-ingestion-api.md) endpoint\) for indexing into the u\_ext\_content schema table.

## 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\}](external-content-ingestion-api.md) 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](../rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](../rest-api-explorer/c_CustomWebServices.md).

### Supported request parameters

<table class="rest_api_path_parameters"><thead><tr><th>

Parameter

</th><th>

Description

</th></tr></thead><tbody><tr><td>

api\_version

</td><td id="version-entry-RESTAPI">

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

</td></tr></tbody>
</table>

|Name|Description|
|----|-----------|
|None| |

|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](../rest-api-explorer/c_RESTAPI.md).

<table class="rest_api_request_headers"><thead><tr><th>

Header

</th><th>

Description

</th></tr></thead><tbody><tr><td>

Accept

</td><td id="accept-JSON-only-entry-RESTAPI">Data format of the response body. Only supports <strong>application/json</strong>.</td></tr><tr><td>

Content-Type

</td><td><p>Data format of the request body.</p>
<p>Valid values:</p>
<ul>
<li><strong>application/msword</strong></li>
<li><strong>application/octet-stream</strong></li>
<li><strong>application/pdf</strong></li>
<li><strong>application/vnd.ms-excel</strong></li>
<li><strong>application/vnd.ms-powerpoint</strong></li>
<li><strong>application/vnd.ms-powerpoint.presentation.macroenabled.12</strong></li>
<li><strong>application/vnd.openxmlformats-officedocument.presentationml.presentation</strong></li>
<li><strong>application/vnd.openxmlformats-officedocument.presentationml.template</strong></li>
<li><strong>application/vnd.openxmlformats-officedocument.spreadsheetml.sheet</strong></li>
<li><strong>application/vnd.openxmlformats-officedocument.wordprocessingml.document</strong></li>
<li><strong>application/vnd.openxmlformats-officedocument.wordprocessingml.template</strong></li>
<li><strong>text/html</strong></li>
<li><strong>text/plain</strong></li>
</ul></td></tr></tbody>
</table>

|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](../rest-api-explorer/c_RESTAPI.md).

|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\)

<table><thead><tr><th>

Element

</th><th>

Description

</th></tr></thead><tbody><tr><td>

error

</td><td>

Object describing the error encountered during processing of the request.

 Data type: Object

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