Seismic public search API provides our customers and partners a programmatic interface to search Seismic content. Developers can query all content that a user has access to using a search term, and further apply a content filter, specify return fields, and sort the search results. ### SCOPES > Requires: `seismic.search` See [Permissions](https://developer.seismic.com/seismicsoftware/reference/scopes) for additional details. ### REQUEST HEADERS Name|Format|Required|Example|Description -|-|-|-|- X-Seismic-Client-Details|base64|No|eyJhcHBsaWNhdGlvbiI6ImFwcGxpY2F0aW9uMSJ9|If provided, the search activity data can be available to customers for reporting and insight analytics purposes. The client details object must contain at least the property “application“, representing the application name with which the search activity will be tagged. Example client details object: { "application": "application1" } ### BODY PARAMETER DEFINITIONS #### Search Term (Optional) `term` specifies the search term against which Seismic search service matches content. { "term": "test" } for example, conducts a full text search for all content containing "test". Correspondingly, a query not specifying a search term or simply providing a completely empty query body, such as empty or `{}` queries all content. #### Search Fields (Optional) `searchFields` specifies where in the content Seismic search service conducts the search. A query can set `searchFields` to be a subset of the fields in the table below. By default, Seismic search service searches all fields. Field|Description -|- name|Content name description|Content description body|Text in the content. It can be normal text or text transformed from image, audio or video. properties|Custom properties For example, {"term":"test","options":{"searchFields":["name","properties"]}} searches for content containing search term "test" in its name or custom properties. #### Return Fields (Optional) `returnFields` specifies the content property fields that Seismic search service returns for matching content found. A query can set `returnFields` to be a subset of the fields in the table below. Field|Return by default?|Description -|-|- repository | Yes | The value can be library (if location is Content Manager or DocCenter or NewsCenter) or WorkSpace name | Yes | Content name teamsiteId | Yes | The teamsiteId of the library content id | Yes | Content id versionId | Yes | Version id type | Yes | Content type. applicationUrls | Yes | Public general links to access the content. Example: `"applicationUrls":[{"name":"DocCenter Universal Link","url":""},{"name":"Content Manager Link","url":""},{"name":"NewsCenter Universal Link","url":""},{"name":"Workspace Share Link","url":""}]` format | Yes | Content format description | No | Content description properties | No | Custom properties. Example: `"properties":[{"name":"CustomProperty","id":"a989dfc5-347f-4ee5-8ad4-71ad188da042","values":[{"id":"1","value":"Presentation & Demo"}]}]` thumbnailUrl | No | A url for the content thumbnail. The token will expire in 1 day. downloadUrl | No | Content download url, if download operation is supported. The token will expire in 1 day. For example, Google documents (e.g. GSlide, GDoc, GSheet) do not include this field as they cannot be downloaded. createdDate | No | Date when content created publishDate | No | Date when content published modifiedDate | No | Date when content last modified majorVersion | No | Content major version minorVersion | No | Content minor version For example, {"term":"test", "options":{"returnFields":["name", "type"]}} searches for all content containing "test", and returns only the name and type of the matching content found. When a query does not explicitly specify the return fields, Seismic search service returns all fields in the table above where "Return by default?" is "Yes". #### Sort Fields (Optional) A query can sort search results returned by the following fields: Field|Description -|- name | Content name createdDate | Date when content created publishDate | Date when content published modifiedDate | Date when content last modified majorVersion | Content major version minorVersion | Content minor version For example, the following query searches for all content containing "test", returns default fields, and sorts the returned search results by content name in ascending / descending order. > {"term":"test", "sort":[{"field":"name","order":"asc|desc"}]} Multiple sort fields can be specified to sort search results on multiple fields. If no sort criteria is provided, Seismic search service returns results sorted by relevance. #### Filtering (Optional) Seismic search service supports filtering through a filter expression in the query. A filter expression can be a single condition or multiple conditions and / or filters connected by filter operators. #### Filter Fields Fields that can be used in filter condition. Field|Type|Description -|-|- repository |string| The value can be library (if location is Content Manager or DocCenter or NewsCenter) or WorkSpace profile |string| Profile name. id |string| Content id cid |string| User generated Content id versionId |string| Version id format |string| Content format createdDate |date| Date when content created publishDate |date| Date when content published modifiedDate |date| Date when content last modified majorVersion |int| Content major version minorVersion |int| Content minor version latestVersion |bool| If true, return only content with the latest version (including minor version) latestApprovedVersion |bool| If true, return only content with the latest major version custom.\ |\| Custom property name. The prefix `custom.` indicates it is filtering by custom property. Note: currently, custom property supports `equal` operator. It also supports `greaterThan` / `greaterThanOrEqual` / `lessThan` / `lessThanOrEqual` when its type is ***date***. For `equal`, if the custom property is of type `multi-value` or `tag`, it is possible to enforce array equality. If the condition value is an `array` of terms, documents will match if and only if the two sets of terms are identical. *Note: date format should follow [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). For more details, please refer to [Conventions and Formats](https://developer.seismic.com/seismicsoftware/reference#introduction-conventions-and-formats)* Supported date examples: `2018-01-01T08:00:00+00:00` `2018-01-01T08:00:00` `2018-01-01T08:00:00Z` `2018-01-01`. #### Condition Operators Seismic search service supports the following condition operators: Operator|Comments -|- in|Check if a field’s value is in a **list**. equal|Check if a field’s value is equal to a **scalar value**. If custom property field is multi-value and field’s value is an array of terms, documents will match if and only if the two sets of terms are identical. greaterThan / greaterThanOrEqual / lessThan / lessThanOrEqual | Compare a field’s value with a single value. The field’s type must be **date** or **int**. Note: currently custom property only supports `equal` operator even if it is **date** or **int** type. For example, to filter content from Seismic that satisfies `repository="library"`, we can set up a filter with a single condition: ``` { "filter": { "operator": "and", "conditions":[ { "attribute": "repository", "operator": "equal", "value": "library" } ] } } ``` *Note: operator must be provided even though there is only one condition* As another example, to filter content from Seismic that satisfies `profile in ("Profile A","Profile B")`, we can set up a filter using the `in` operator: ``` { "filter": { "operator": "and", "conditions": [ { "attribute": "profile", "operator": "in", "value": [ "Profile A", "Profile B" ] } ] } } ``` #### Filter Operators Seismic search service supports `and`, `or` filter operators. We can use these filter operators to construct more complex filters. For example, to filter content from Seismic that satisfies `repository="library" AND format="TXT"`, we can use the `and` operator to set up the following filter: ``` { "filter": { "operator": "and", "conditions": [ { "attribute": "repository", "operator": "equal", "value": "library" }, { "attribute": "format", "operator": "equal", "value": "TXT" } ] } } ``` *Note: currently the max filter depth is 2.* To demonstrate a filter of maximum depth of 2, we can query for content that satisfies `latestApprovedVersion=true AND ((repository="library" AND format="TXT") OR (repository="workspace" AND format="PPTX"))`. The corresponding filter using the combination of `and` and `or` operators is: ``` { "filter": { "operator": "and", "conditions": [ { "attribute": "latestVersion", "operator": "equal", "value": true } ], "filters": [ { "operator": "or", "filters": [ { "operator": "and", "conditions": [ { "attribute": "repository", "operator": "equal", "value": "library" }, { "attribute": "format", "operator": "equal", "value": "TXT" } ] }, { "operator": "and", "conditions": [ { "attribute": "repository", "operator": "equal", "value": "workspace" }, { "attribute": "format", "operator": "equal", "value": "PPTX" } ] } ] } ] } } ``` #### Filter Expression In general, a `filter` is constructed with a group of `conditions` and a group of `filters`. The items in `conditions` and `filters` are connected with same `operator`. A `condition` is a single conditional expression (e.g. `repository="library"`), whereas a `filter` is a logical grouping of `conditions`. `filters` can be empty or a list of `filter`s, as described above. `operator` is always needed in a filter expression. ``` { "filter": { "operator": "and|or", "conditions": [ { "attribute": "field name", "operator": "in|equal|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual", "value": "value that needs to match" } ], "filters": [] } } ``` #### Page Size (Optional) Seismic search service organizes search results returned by pages. Page size, which specifies the number of search results that a page can hold, ranges between 0 and 100, with a default value of 40. To specify a page size of 5, we can use: {"options":{"pageSize":5}} #### Pagination If search results span multiple pages, the response will contain a `continuationToken` property of non-null value. A request with parameter `?continuationToken=` in the request URL fetches the next page of the search results, and **body** is not required in this case. #### Validation Rules And Errors Seismic search service performs validation on incoming requests. The table below provides validation rules, error codes, and corresponding error messages. If there are multiple errors in the request, only the first one captured is returned. Validation Rule | Error Code | Error Message -|-|- Auth token expired, invalid, or not provided | 401 | Unauthorized Request Search term should be less than 150 characters | 400 | Search term should be less than 150 characters Field used for filtering not found | 400 | Filter field \ not found Custom Property Field used for date range filter not found | 400 | Not found the date property \. Field to be searched on not found | 400 | Search field \ not found Field to be returned in the result not found | 400 | Return field \ not found Field to be sorted on not found | 400 | Sort field \ not found Order value not supported | 400 | Order value \ not supported. Try ASC or DESC Incorrect page size | 400 | PageSize \ is incorrect. Please set a value between 0-100 Unsupported operator | 400 | Operator \ not supported. Please use AND\|OR\. Filter too complex | 400 | Filter is too complex. Currently the max filter depth is 2. DateTime format invalid | 400 | Invalid DateTime format \ for \ condition Continuation Toke timeout | 400 | continuationToken is invalid or expired. Please regenerate it. Custom property equal to array value invalid | 400 | \ is not a multi-value custom property, so an array value is not allowed.