Content Search

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 for additional details.

REQUEST HEADERS

NameFormatRequiredExampleDescription
X-Seismic-Client-Detailsbase64NoeyJhcHBsaWNhdGlvbiI6ImFwcGxpY2F0aW9uMSJ9If 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.

FieldDescription
nameContent name
descriptionContent description
bodyText in the content. It can be normal text or text transformed from image, audio or video.
propertiesCustom 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.

FieldReturn by default?Description
repositoryYesThe value can be library (if location is Content Manager or DocCenter or NewsCenter) or WorkSpace
nameYesContent name
teamsiteIdYesThe teamsiteId of the library content
idYesContent id
versionIdYesVersion id
typeYesContent type.
applicationUrlsYesPublic general links to access the content. Example: "applicationUrls":[{"name":"DocCenter Universal Link","url":"<DocCenterLink>"},{"name":"Content Manager Link","url":"<ContentManagerLink>"},{"name":"NewsCenter Universal Link","url":"<NewsCenterLink>"},{"name":"Workspace Share Link","url":"<WorkspaceLink>"}]
formatYesContent format
descriptionNoContent description
propertiesNoCustom properties. Example: "properties":[{"name":"CustomProperty","id":"a989dfc5-347f-4ee5-8ad4-71ad188da042","values":[{"id":"1","value":"Presentation & Demo"}]}]
thumbnailUrlNoA url for the content thumbnail. The token will expire in 1 day.
downloadUrlNoContent 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.
createdDateNoDate when content created
publishDateNoDate when content published
modifiedDateNoDate when content last modified
majorVersionNoContent major version
minorVersionNoContent 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:

FieldDescription
nameContent name
createdDateDate when content created
publishDateDate when content published
modifiedDateDate when content last modified
majorVersionContent major version
minorVersionContent 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.

FieldTypeDescription
repositorystringThe value can be library (if location is Content Manager or DocCenter or NewsCenter) or WorkSpace
profilestringProfile name.
idstringContent id
cidstringUser generated Content id
versionIdstringVersion id
formatstringContent format
createdDatedateDate when content created
publishDatedateDate when content published
modifiedDatedateDate when content last modified
majorVersionintContent major version
minorVersionintContent minor version
latestVersionboolIf true, return only content with the latest version (including minor version)
latestApprovedVersionboolIf true, return only content with the latest major version
custom.<CustomPropertyName><defined in system>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. For more details, please refer to 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:

OperatorComments
inCheck if a field’s value is in a list.
equalCheck 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 / lessThanOrEqualCompare 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 filters, 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=<continuationTokenValue> 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 RuleError CodeError Message
Auth token expired, invalid, or not provided401Unauthorized Request
Search term should be less than 150 characters400Search term should be less than 150 characters
Field used for filtering not found400Filter field <field> not found
Custom Property Field used for date range filter not found400Not found the date property <field>.
Field to be searched on not found400Search field <field> not found
Field to be returned in the result not found400Return field <field> not found
Field to be sorted on not found400Sort field <field> not found
Order value not supported400Order value <order> not supported. Try ASC or DESC
Incorrect page size400PageSize <size> is incorrect. Please set a value between 0-100
Unsupported operator400Operator <operator> not supported. Please use AND|OR.
Filter too complex400Filter is too complex. Currently the max filter depth is 2.
DateTime format invalid400Invalid DateTime format <value> for <field> condition
Continuation Toke timeout400continuationToken is invalid or expired. Please regenerate it.
Custom property equal to array value invalid400<field> is not a multi-value custom property, so an array value is not allowed.
Language
Authorization
Header
Click Try It! to start a request and see the response here!