The TISC API provides endpoints to add and retrieve threat intelligence data in the Threat Intelligence Security Center (TISC) application.
Data retrieved by this API can be used by other security tools such as Security Information Event Management (SIEM) systems. SIEM systems can integrate with TISC using this API to retrieve observables related to threats in TISC and automatically detect and monitor these threats within an organization’s network. This API enables bidirectional sharing of observables from security tools. SIEM systems observe anomalous activity in the environment and can provide a list of observables associated with the anomalous activity to TISC.
This API can also be used to enrich SIEM alerts with threat intelligence context. For example, if a SIEM alert is generated based on unusually high traffic from an IP address, TISC can provide additional information such as whether the IP address or domain involved is linked to known malicious activities. This enrichment data enables security analysts to triage the alerts and use the contextual information for efficient remediation.
This API requires the Threat Intelligence Security Center application, which is available on the ServiceNow Store.
TISC API - POST /sn_sec_tisc/threat_intel_data/add_observables
Adds observable source records to the Threat Intelligence Security Center (TISC) application.
The observable source records are created in the Observable Source [sn_sec_tisc_observable_source] table and are processed through de-duplication and aggregation in the TISC data flow.
Note: Observable source records can't be directly updated using this endpoint. Only new records can be created. Therefore, even if only a few fields require an update, all fields must still be included in the request.
To access this endpoint, the caller must have the sn_sec_tisc.api_obs_write_access role, which by default is included in the Threat Intelligence administrator role (sn_sec_tisc.admin).
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
Name
Description
None
Name
Description
observables
Required. List of observable objects to add to TISC. For each observable object, an observable source record is created if all validations are passed, with the source as defined by the source parameter in the request body.Data type: Array of Objects
Field-value pairs containing attribute data about the observable. Attributes are specific to an observable type, such as the AS number for an IP address or the socket type for a network. All attributes for all observable types are supported. For a complete list of valid attributes, see the Observable attributes section below. Data type: Object
"attributes": {
"<field>": "<value>"
}
observables.<field>
Name-value pairs containing general data about the observable. The fields that can be provided in this parameter are common to all observable types.The type and value fields are required for all observables.
Note: Follow these guidelines for providing values:
All dates must be in ISO format in the UTC timezone.
Some fields require values from a specified table or have a list of possible values. If invalid values are provided for these fields, the observable source record is still created but the invalid values are skipped.
Valid fields:
additional_context
Additional context about the observable.
attack_phases
List of attack phase names as a comma separated value. For a complete list of valid attack phases, see the Kill Chain Phase Name field in the Kill Chain Phase [sn_sec_tisc_kill_chain_phase] table.
For example:
</code></pre>
<p>"attack_phases": "Lockheed Martin: Reconnaissance,Lockheed Martin: Installation"
```</p>
<ul>
<li><strong>author</strong></li>
</ul>
<p>Author for the observable.</p>
<ul>
<li><strong>confidence</strong></li>
</ul>
<p>The confidence that the source system has in the correctness of the observable data. Must be a number from 0–100.</p>
<ul>
<li><strong>description</strong></li>
</ul>
<p>Description of the observable.</p>
<ul>
<li><strong>expiration_time</strong></li>
</ul>
<p>Expiration date of the observable record.</p>
<ul>
<li><strong>external_source_id</strong></li>
</ul>
<p>External ID of the observable from the source system.</p>
<ul>
<li><strong>first_observed</strong></li>
</ul>
<p>Date the data was first seen.</p>
<ul>
<li><strong>first_seen</strong></li>
</ul>
<p>Date this observable was first seen performing malicious activities.</p>
<ul>
<li><strong>last_observed</strong></li>
</ul>
<p>Date the data was last seen.</p>
<ul>
<li><strong>last_seen</strong></li>
</ul>
<p>Date this observable was last seen performing malicious activities.</p>
<ul>
<li><strong>notes</strong></li>
</ul>
<p>Any additional notes for the observable. Can be formatted as HTML.</p>
<ul>
<li><strong>reputation</strong></li>
</ul>
<p>Reputation of the observable.</p>
<p>Possible values:</p>
<ul>
<li>clear</li>
<li>malicious</li>
<li>suspicious</li>
<li>unknown</li>
<li><strong>source_reported_score</strong></li>
</ul>
<p>Maliciousness score of the observable reported by the source system. Must be a number from 0–100.</p>
<ul>
<li><strong>tags</strong></li>
</ul>
<p>List of tags as a comma-separated value. For a complete list of valid tags, see the <strong>Name</strong> field in the Tag [sn_sec_tisc_tag] table. If the provided tag doesn’t exist, the tag is automatically created and associated with the observable.</p>
<ul>
<li><strong>taxonomies</strong></li>
</ul>
<p>List of taxonomies as a comma-separated value. For a complete list of valid taxonomies, see the <strong>Taxonomy Value</strong> field in the Taxonomy Value [sn_sec_tisc_taxonomy_value] table.</p>
<ul>
<li><strong>threat_level</strong></li>
</ul>
<p>Threat level of the observable.</p>
<p>Possible values:</p>
<ul>
<li>low</li>
<li>medium</li>
<li>high</li>
<li><strong>threat_severity</strong></li>
</ul>
<p>Threat severity of the observable.</p>
<p>Possible values:</p>
<ul>
<li>low</li>
<li>medium</li>
<li>high</li>
<li>critical</li>
<li><strong>tlp</strong></li>
</ul>
<p>Data sensitivity level for the observable using the traffic light protocol (TLP).</p>
<p>Possible values:</p>
<ul>
<li>CLEAR</li>
<li>GREEN</li>
<li>AMBER</li>
<li>AMBER+STRICT</li>
<li>
<p>RED
Table: In the Label field in the TLP Label [sn_sec_tisc_tlp_label] table.</p>
</li>
<li>
<p><strong>type</strong></p>
</li>
</ul>
<p>Required. Type of observable.</p>
<p>For a complete list of valid observable types, see the <strong>Value</strong> field in the Observable Type [sn_sec_tisc_observable_type] table, or the Observable attributes section below.</p>
<ul>
<li><strong>usage_categories</strong></li>
</ul>
<p>List of usage categories as a comma-separated value. For a complete list of valid usage categories, see the <strong>Usage Category</strong> field in the Usage Category [sn_sec_tisc_usage_category] table.</p>
<ul>
<li><strong>value</strong></li>
</ul>
<p>Required. Value associated with the observable, such as an IP address or URL.</p>
<p>Data type: String</p>
<p>Table: Observable Source [sn_sec_tisc_observable_source]</p></td></tr><tr><td>
source
</td><td>
Required. Source that originally detected the observables, such as a SIEM system.The source is used for all observables listed in the API request.
Data type: String
Stored in: Sources provided in the request body are added to the API Integration \[sn\_sec\_tisc\_api\_integration\] table.
</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).
<table id="table_gcj_124_xbc"><thead><tr><th>
Status code
</th><th>
Description
</th></tr></thead><tbody><tr><td>
200
</td><td id="entry-200-status-code">
Successful. The request was successfully processed.
</td></tr><tr><td>
400
</td><td>Bad request. The request parameters are invalid or the request body JSON has a syntactical error.To view details about the error, see the <strong>error</strong> parameter in the response body.</td></tr><tr><td>
401
</td><td>
Unauthorized. The user authentication is invalid. Check the user name and password or OAuth token.
</td></tr><tr><td>
403
</td><td>
Forbidden. The calling user is missing a required role. The sn\_sec\_tisc.api\_obs\_write\_access role is required to access this endpoint.
</td></tr><tr><td>
429
</td><td>
Too many requests. The number of API requests exceeds the rate limit for the API. By default, the limit is 100 requests per hour.
</td></tr><tr><td>
500
</td><td>
Internal server error. Check application logs in the Log \[syslog\] table for more information about the error.
</td></tr></tbody>
</table>
### Response body parameters \(JSON\)
<table><thead><tr><th>
Name
</th><th>
Description
</th></tr></thead><tbody><tr><td>
error
</td><td>
Error information. This parameter is only returned if the request failed.Data type: Object
</td></tr><tr><td>
error.message
</td><td>
Error message containing the reason the request failed.Data type: String
</td></tr><tr><td>
error.detail
</td><td>
Additional details about why the request failed.Data type: String
</td></tr><tr><td>
error\_records
</td><td>
Details about the observables included in the request that couldn't be added to TISC.Data type: Array of Objects
</td></tr><tr><td>
error\_records.error\_message
</td><td>
Error message that explains why a record couldn't be created for the observable.Data type: String
</td></tr><tr><td>
error\_records.type
</td><td><p>Type of observable.For a complete list of valid observable types, see the <strong>Value</strong> field in the Observable Type [sn_sec_tisc_observable_type] table, or the Observable attributes section below.</p>
<p>Data type: String</p></td></tr><tr><td>
error\_records.value
</td><td>
Value associated with the observable, such as an IP address or URL.Data type: String
</td></tr><tr><td>
metadata
</td><td>
Metadata about the number of records created by the API request.
"metadata": {
"error_records": Number,
"success_records": Number,
"total_records": Number
}
Data type: Object
</td></tr><tr><td>
metadata.error\_records
</td><td>
Number of observables included in the request that couldn't be added to TISC.Data type: Number
</td></tr><tr><td>
metadata.success\_records
</td><td>
Number of observable records that were successfully created in TISC.Data type: Number
</td></tr><tr><td>
metadata.total\_records
</td><td>
Total number of observables included in the request.Data type: Number
</td></tr><tr><td>
status
</td><td><p>Status of the API request.Possible values:</p>
<ul>
<li><code>error</code>: No observables successfully added to TISC.</li>
<li><code>failure</code>: The request failed due to a bad request or system error. See the <strong>error</strong> parameter in the response body for more information about the error.</li>
<li><code>partial_success</code>: Some observables successfully added to TISC.</li>
<li><code>success</code>: All observables successfully added to TISC.</li>
</ul>
<p>Data type: String</p></td></tr><tr><td>
success\_records
</td><td>
Details about the observable records that were successfully created.Data type: Array of Objects
## TISC API - POST /sn\_sec\_tisc/threat\_intel\_data/observables
Retrieves observables data, including relationships between observables and other threat intelligence data such as Structured Threat Information Expression \(STIX\) objects.
Observables returned in the response are sorted by **sys\_id** in ascending order.
For more information about observables and STIX objects, see [IoC Repository](../../security-management/ioc-repository.md).
To access this endpoint, the caller must have the sn\_sec\_tisc.api\_obs\_read\_access role, which by default is included in the Threat Intelligence administrator role \(sn\_sec\_tisc.admin\).
### URL format
Versioned URL: `/api/sn_sec_tisc/{api_version}/threat_intel_data/observables`
Default URL: `/api/sn_sec_tisc/threat_intel_data/observables`
**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>
Name
</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| |
<table class="rest_api_request_body"><thead><tr><th>
Name
</th><th>
Description
</th></tr></thead><tbody><tr><td>
included\_fields
</td><td>
Fields to return for observables, observable references, and STIX objects in the response. Different fields can be returned for observables, references, and each type of STIX object.ServiceNow system fields, except for sys\_created\_on, sys\_updated\_on, and sys\_id, aren't returned in the response.
Data type: Object
Default: Returns the fields syd\_id, type, and value for all observable types.
</td></tr><tr><td>
included\_fields.observable.attributes
</td><td>
Fields to return for specified observable types. Data type: Object
"attributes": {
"": {Object}
}
Default: No fields specific to an observable type are returned. Only the fields syd\_id, type, and value are returned.
</td></tr><tr><td>
included\_fields.observable.attributes.<observable\_type>
</td><td>
Fields to return for an observable type.Data type: Object
Replace `<observable_type>` with the name of the observable type, such as `artifact`. For a complete list of valid observable types, see the Value field in the Observable Type \[sn\_sec\_tisc\_observable\_type\] table.
</td></tr><tr><td>
included\_fields.observable.attributes.<observable\_type>.include\_all\_fields
</td><td><p>Flag that indicates whether to return all available fields for the observable type.Valid values:</p>
<ul>
<li>true: Return all fields for the observable type.</li>
<li>false: Only return fields specified in the <strong>values</strong> parameter for the observable type.</li>
</ul>
<p>Data type: Boolean</p></td></tr><tr><td>
included\_fields.observable.attributes.<observable\_type>.values
</td><td><p>List of fields to return for the observable type. Only use this parameter if the value of <strong>include_all_fields</strong> is false.Data type: Array of Strings</p>
<div class="highlight"><pre><span></span><code>"values": [
"String"
]
</code></pre></div>
<p>The fields provided must be column_names from the table for the observable type. The following tables are used for observable types.</p>
<ul>
<li>Artifact [sn_sec_tisc_artifact]</li>
<li>AS Number [sn_sec_tisc_as_number]</li>
<li>Directory [sn_sec_tisc_directory]</li>
<li>Domain Name [sn_sec_tisc_domain_name]</li>
<li>Email Address [sn_sec_tisc_email_address]</li>
<li>Email Message [sn_sec_tisc_email_message]</li>
<li>Email Subject [sn_sec_tisc_email_subject]</li>
<li>File [sn_sec_tisc_file]</li>
<li>IPv4 Address [sn_sec_tisc_ipv4_address]</li>
<li>IPv4 CIDR [sn_sec_tisc_ipv4_cidr]</li>
<li>IPv6 Address [sn_sec_tisc_ipv6_address]</li>
<li>IPv6 CIDR [sn_sec_tisc_ipv6_cidr]</li>
<li>MAC Address [sn_sec_tisc_mac_address]</li>
<li>MD5 Hash [sn_sec_tisc_md5_hash]</li>
<li>Mutex Name [sn_sec_tisc_mutex_name]</li>
<li>Network [sn_sec_tisc_network]</li>
<li>Other Observable [sn_sec_tisc_other_observable]</li>
<li>Process [sn_sec_tisc_process]</li>
<li>SHA1 Hash [sn_sec_tisc_sha1_hash]</li>
<li>SHA256 Hash [sn_sec_tisc_sha256_hash]</li>
<li>SHA512 Hash [sn_sec_tisc_sha512_hash]</li>
<li>Software [sn_sec_tisc_software]</li>
<li>URL [sn_sec_tisc_url]</li>
<li>User Account [sn_sec_tisc_user_account]</li>
<li>Windows Registry Key [sn_sec_tisc_windows_registry_key]</li>
<li>X.509 Certificate [sn_sec_tisc_x_509_certificate]</li>
</ul></td></tr><tr><td>
included\_fields.observable.common\_fields
</td><td>
Fields to return for all observable types.The fields must be from the Observable \[sn\_sec\_tisc\_observable\] table because they must be common to all observable types.
Data type: Object
Default: Returns the fields syd\_id, type, and value for all observable types.
</td></tr><tr><td>
included\_fields.observable.common\_fields.include\_all\_fields
</td><td><p>Flag that indicates whether to return all fields from the Observable [sn_sec_tisc_observable] table for all observable types.Valid values:</p>
<ul>
<li>true: Return all fields from the Observable [sn_sec_tisc_observable] table.</li>
<li>false: Only return fields specified in the <strong>common_fields.values</strong> parameter.</li>
</ul>
<p>Data type: Boolean</p></td></tr><tr><td>
included\_fields.observable.common\_fields.values
</td><td><p>List of fields to return for all observable types. Only use this parameter if the value of <strong>common_fields.include_all_fields</strong> is false.Data type: Array of Strings</p>
<div class="highlight"><pre><span></span><code>"values": [
"String"
]
</code></pre></div>
<p>The fields provided must be column names from the Observable [sn_sec_tisc_observable] table.</p></td></tr><tr><td>
included\_fields.reference
</td><td>
Fields to return for observable references. Observable references are external references used to describe pointers to information represented outside of STIX.Data type: Object
Default: Returns the fields reference\_source, sys\_id, and url.
</td></tr><tr><td>
included\_fields.reference.include\_all\_fields
</td><td><p>Flag that indicates whether to return all available fields for observable references.Valid values:</p>
<ul>
<li>true: Return all fields for observable references.</li>
<li>false: Only return fields specified in the <strong>reference.values</strong> parameter.</li>
</ul>
<p>Data type: Boolean</p></td></tr><tr><td>
included\_fields.reference.values
</td><td><p>List of fields to return for observable references. Only use this parameter if the value of <strong>reference.include_all_fields</strong> is false.Data type: Array of Strings</p>
<div class="highlight"><pre><span></span><code>"values": [
"String"
]
</code></pre></div>
<p>The fields provided must be column names from the Observable Reference [sn_sec_tisc_observable_reference] table.</p></td></tr><tr><td>
included\_fields.<stix\_object>
</td><td>
Object containing fields to return for a STIX object type.Data type: Object
Replace `<stix_object>` with the name of the STIX object type, such as `attack_pattern`.
Valid STIX object types:
- attack\_pattern
- campaign
- course\_of\_action
- data\_component
- data\_source
- grouping
- identity
- incident
- indicator
- infrastructure
- intrusion\_set
- location
- malware
- malware\_analysis
- note
- observed\_data
- opinion
- report
- threat\_actor
- tool
- vulnerability
Default: Returns the fields id, name, and sys\_id.
</td></tr><tr><td>
included\_fields.<stix\_object>.include\_all\_fields
</td><td><p>Flag that indicates whether to return all available fields for the STIX object type.Valid values:</p>
<ul>
<li>true: Return all fields for the STIX object type.</li>
<li>false: Only return fields specified in the <strong>values</strong> parameter for the STIX object type.</li>
</ul>
<p>Data type: Boolean</p></td></tr><tr><td>
included\_fields.<stix\_object>.values
</td><td><p>List of fields to return for the STIX object type. Only use this parameter if the value of <strong>include_all_fields</strong> is false.Data type: Array of Strings</p>
<div class="highlight"><pre><span></span><code>"values": [
"String"
]
</code></pre></div>
<p>The fields provided must be column_names from the table for the STIX object type. The following tables are used for STIX objects.</p>
<ul>
<li>Attack Pattern [sn_sec_tisc_attack_pattern]</li>
<li>Campaign [sn_sec_tisc_campaign]</li>
<li>Course of Action [sn_sec_tisc_course_of_action]</li>
<li>Data Component [sn_sec_tisc_aggregated_data_component]</li>
<li>Data Source [sn_sec_tisc_aggregated_data_source]</li>
<li>Grouping [sn_sec_tisc_threat_grouping]</li>
<li>Identity [sn_sec_tisc_identity]</li>
<li>Incident [sn_sec_tisc_threat_event]</li>
<li>Indicator [sn_sec_tisc_indicator]</li>
<li>Infrastructure [sn_sec_tisc_infrastructure]</li>
<li>Intrusion Set [sn_sec_tisc_intrusion_set]</li>
<li>Location [sn_sec_tisc_location]</li>
<li>Malware [sn_sec_tisc_malware]</li>
<li>Malware Analysis [sn_sec_tisc_malware_analysis]</li>
<li>Note [sn_sec_tisc_threat_note]</li>
<li>Observed Data [sn_sec_tisc_observed_data]</li>
<li>Opinion [sn_sec_tisc_threat_opinion]</li>
<li>Report [sn_sec_tisc_threat_report]</li>
<li>Threat Actor [sn_sec_tisc_threat_actor]</li>
<li>Tool [sn_sec_tisc_tool]</li>
<li>Vulnerability [sn_sec_tisc_vulnerability]</li>
</ul></td></tr><tr><td>
observable\_filters
</td><td>
Filters to apply to the observables. Only observables that match the filter criteria are returned in the response.Data type: Object
Default: Empty object \(no filters applied\)
</td></tr><tr><td>
observable\_filters.boolean\_operator
</td><td>
Boolean operator to use for the filter conditions.Valid values:
- AND: Return observables that meet all filter conditions.
- OR: Return observables that meet at least one of the filter conditions.
Data type: String
</td></tr><tr><td>
observable\_filters.filters
</td><td>
Filters to apply to the observables. Each filter object can be simple or complex.
- Simple filters contain a field name, operator, and value.
- Complex filters contain a Boolean operator and an array of simple filters. The Boolean operator is applied to the array of simple filters.
Data type: Array of Objects
</td></tr><tr><td>
observable\_filters.filters.field\_name
</td><td>
Name of the field to use to filter the observables. Valid values:
- confidence
- reputation
- security\_type
- status
- sys\_created\_on
- sys\_updated\_on
- tags
- taxonomies
- threat\_score
- type
- value
- watch\_list
Data type: String
</td></tr><tr><td>
observable\_filters.filters.operator
</td><td><p>Operator to use for the filter.For more information about operators, see <a href="../../../platform-user-interface/r_OpAvailableFiltersQueries/">Operators available for filters and queries</a>.</p>
<p>The data type of the filter field determines the valid operators. The following operators are valid for each data type.</p>
<ul>
<li><strong>Boolean</strong></li>
</ul>
<p>Applicable field: watch_list</p>
<ul>
<li>!=</li>
<li>=</li>
<li>ISEMPTY</li>
<li>ISNOTEMPTY</li>
<li><strong>Choice</strong></li>
</ul>
<p>Applicable fields: reputation, security_type, status</p>
<ul>
<li>!=</li>
<li>=</li>
<li>ENDSWITH</li>
<li>IN</li>
<li>LIKE</li>
<li>NOT IN</li>
<li>NOT LIKE</li>
<li>STARTSWITH</li>
<li><strong>Date-time</strong></li>
</ul>
<p>Applicable fields: sys_created_on, sys_updated_on</p>
<ul>
<li><</li>
<li><=</li>
<li>></li>
<li>>=</li>
<li>ISEMPTY</li>
<li>ISNOTEMPTY</li>
<li>NOTON</li>
<li>ON</li>
<li><strong>GlideList</strong></li>
</ul>
<p>Applicable fields: tags, taxonomies</p>
<ul>
<li>IN</li>
<li>NOT IN</li>
</ul>
<p><strong>Note:</strong> Must use a single valid, existing value for the filter condition, and empty observable field values aren't considered a match.</p>
<ul>
<li>ISEMPTY</li>
<li>ISNOTEMPTY</li>
<li>LIKE</li>
</ul>
<p><strong>Note:</strong> Must use a single value for the filter condition.</p>
<ul>
<li>NOT LIKE</li>
</ul>
<p><strong>Note:</strong> Must use a single value for the filter condition, and empty observable field values aren't considered a match.</p>
<ul>
<li><strong>Number</strong></li>
</ul>
<p>Applicable fields: confidence, threat_score</p>
<ul>
<li>!=</li>
<li><=</li>
<li>=</li>
<li>>=</li>
<li>ISEMPTY</li>
<li>ISNOTEMPTY</li>
<li><strong>Reference</strong></li>
</ul>
<p>Applicable field: type</p>
<ul>
<li>!=</li>
<li>=</li>
<li>IN</li>
<li>ISEMPTY</li>
<li>ISNOTEMPTY</li>
<li><strong>String</strong></li>
</ul>
<p>Applicable field: value</p>
<ul>
<li>!=</li>
<li><=</li>
<li>=</li>
<li>>=</li>
<li>ENDSWITH</li>
<li>IN</li>
<li>ISEMPTY</li>
<li>ISNOTEMPTY</li>
<li>LIKE</li>
<li>NOT LIKE</li>
<li>STARTSWITH</li>
</ul>
<p>Data type: String</p></td></tr><tr><td>
observable\_filters.filters.field\_value
</td><td><p>Value of the field.For choice fields, the value must be the internal value, not the display value. For date-time fields, the value must be in ISO format in the UTC timezone.</p>
<p><strong>Note:</strong> This parameter isn’t required when using the ISEMPTY or ISNOTEMPTY operators.</p>
<p>Data type: String</p></td></tr><tr><td>
page\_size
</td><td>
Limits the number of observables that are returned in the API response. Used for pagination.Data type: String
Default: 100
Maximum value: 1000
</td></tr><tr><td>
page\_token
</td><td><p>Used to get observables data for the current page.To get the first page, this parameter can be omitted or the value for this parameter must be an empty string. To get the next page in the following request, use the <strong>next_page_token</strong> value from the response body as the value for this parameter.</p>
<p>Data type: String</p>
<p>Default: Empty string</p></td></tr><tr><td>
relationships
</td><td>
Relationship types to return for each observable in the response. The relationships can be with another observable, an observable reference, or a Structured Threat Information Expression \(STIX\) object.
Valid values:
- attack\_pattern
- campaign
- course\_of\_action
- data\_component
- data\_source
- grouping
- identity
- incident
- indicator
- infrastructure
- intrusion\_set
- location
- malware
- malware\_analysis
- note
- observable
- observed\_data
- opinion
- reference
- report
- threat\_actor
- tool
- vulnerability
For example, passing the array `["observable", "threat_actor"]` returns all related observables and threat actors for each observable in the response.
Data type: Array
Default: Empty array \(no relationships returned\)
</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).
<table><thead><tr><th>
Status code
</th><th>
Description
</th></tr></thead><tbody><tr><td>
200
</td><td id="entry-200-status-code">
Successful. The request was successfully processed.
</td></tr><tr><td>
400
</td><td>Bad request. The request parameters are invalid or the request body JSON has a syntactical error.To view details about the error, see the <strong>error</strong> parameter in the response body.</td></tr><tr><td>
401
</td><td>
Unauthorized. The user authentication is invalid. Check the user name and password or OAuth token.
</td></tr><tr><td>
403
</td><td>
Forbidden. The calling user is missing a required role. The sn\_sec\_tisc.api\_obs\_read\_access role is required to access this endpoint.
</td></tr><tr><td>
429
</td><td>
Too many requests. The number of API requests exceeds the rate limit for the API. By default, the limit is 500 requests per hour.
</td></tr><tr><td>
500
</td><td>
Internal server error. Check application logs in the Log \[syslog\] table for more information about the error.
</td></tr></tbody>
</table>
### Response body parameters \(JSON\)
<table><thead><tr><th>
Name
</th><th>
Description
</th></tr></thead><tbody><tr><td>
error
</td><td>
Error information. This parameter is only returned if the request failed.Data type: Object
</td></tr><tr><td>
error.message
</td><td>
Error message containing the reason the request failed.Data type: String
</td></tr><tr><td>
error.detail
</td><td>
Additional details about why the request failed.Data type: String
</td></tr><tr><td>
is\_last\_page
</td><td>
Flag that indicates whether this is the last page of observables data.Valid values:
- true: This response contains the last page of data.
- false: There are additional pages that can be returned.
Data type: Boolean
</td></tr><tr><td>
next\_page\_token
</td><td>Use this value in the next API request to get the next page of observables data. Provide this value in the <strong>page_token</strong> parameter in the request body.Data type: String</td></tr><tr><td>
observables
</td><td><p>Observables objects. Data type: Array of Objects</p>
<div class="highlight"><pre><span></span><code>"observables": [
{
"attributes": {Object},
"relationships": {Object},
"sys_id": "String",
"type": "String",
"value": "String"
}
]
</code></pre></div>
<p>Each observables object also includes the fields specified by the <strong>included_fields.observable.common_fields</strong> parameter in the request body.</p></td></tr><tr><td>
observables.attributes
</td><td><p>Name-value pairs for the fields specified by the <strong>included_fields.observable.attributes.<observable_type></strong> parameter in the request body.Data type: Object</p>
<div class="highlight"><pre><span></span><code>"attributes": {
"<field>": "<value>"
}
</code></pre></div></td></tr><tr><td>
observables.relationships
</td><td><p>Relationships for the observable. The types of relationships returned are specified by the <strong>relationships</strong> parameter in the request body, and the fields returned for each relationship are specified by the <strong>included_fields</strong> parameter in the request body.This example shows the basic structure of this parameter. However, the relationship types and fields returned vary based on the request body parameters.</p>
<p>Data type: Object</p>
<div class="highlight"><pre><span></span><code>"relationships": {
"observable": [
{
"sys_id": "String",
"type": "String",
"value": "String"
}
],
"indicator": [
{
"id": "String",
"name": "String",
"sys_id": "String"
}
],
"attack_pattern": [
{
"id": "String",
"name": "String",
"sys_id": "String"
}
]
}
</code></pre></div></td></tr><tr><td>
observables.sys\_id
</td><td>
Sys\_id of the observable.Data type: String
Table: Observable \[sn\_sec\_tisc\_observable\]
</td></tr><tr><td>
observables.type
</td><td>Type of observable. For a complete list of valid observable types, see the <strong>Value</strong> field in the Observable Type [sn_sec_tisc_observable_type] table.Data type: String</td></tr><tr><td>
observables.value
</td><td>
Value associated with the observable, such as an IP address or URL.Data type: String
</td></tr><tr><td>
origin
</td><td>
Origin application of the response, which is Threat Intelligence Security Center \(TISC\). The value of this parameter is `sn_sec_tisc`.This value can optionally be used by SIEMs consuming the API response to trace whether the intelligence from TISC resulted in the creation of security incidents.
Data type: String
</td></tr><tr><td>
page\_size
</td><td>
Maximum number of observables returned in the response. Used for pagination.Data type: String
</td></tr><tr><td>
status
</td><td><p>Status of the API request.Possible values:</p>
<ul>
<li>failure</li>
<li>success</li>
</ul>
<p>If the request failed, see the <strong>error</strong> parameter in the response body for more information about the error.</p>
<p>Data type: String</p></td></tr></tbody>
</table>
### cURL request
This example returns the first page of observables data. The **observable\_filters** parameter specifies to return only observables that match the condition `status = active AND [threat_score >= 70 OR confidence >= 50]`.