Skip to main content
This endpoint lets you search for documents by using advanced filters and free text queries. Free text queries are matched against the documents’ filenames and contents.

​
Free text search

​
Boolean operators

The + symbol represents an AND operation, and the | symbol represents an OR. Searching for lorem + ipsum will match documents containing both “lorem” AND “ipsum” in the filename or content. Similarly, searching for lorem | ipsum will match documents containing either “lorem” OR “ipsum” in the filename or content. The default operator between the search keywords is AND. That means that searching for two terms without any operator, for example, lorem ipsum, will match documents containing both the words “lorem” and “ipsum” in the filename or content. You can use the operator - to exclude documents containing a specific word. For instance, the search lorem -ipsum will match documents that contain the word “lorem”, but does NOT contain the word “ipsum”.

​
Phrases

Enclose multiple words inside double quotes " to group these words together. Normally, the search query lorem ipsum will match not only “lorem ipsum” but also “lorem cognite ipsum”, and in general, there can be any number of words between the two words in the query. The search query "lorem ipsum", however, will match only exactly “lorem ipsum” and not “lorem cognite ipsum”.

​
Escape

To search for the special characters (+, |, -, ", \), escape with a preceding backslash \.

​
Ordering

When you search for a term, the endpoint tries to return the most relevant documents first, with less relevant documents further down the list. There are a few factors that determine the relevance of a document:
  • If the search terms are found multiple times within a document, the relevance of that document is higher.
  • For searches with multiple terms, documents containing all the terms are considered more relevant than documents containing only some.
  • Matches of the terms in the filename field of the document are more relevant than matches in the document’s content.

​
Examples

The following request will return documents matching the specified search query. 
{
  "search": {
    "query": "cognite \"lorem ipsum\""
  }
}
The following example combines a query with a filter. The search request will return documents matching the search query, where externalId starts with “1”. The results will be ordered by how well they match the query string. 
{
    "search": {
        "query": "cognite \"lorem ipsum\""
    },
    "filter": {
        "prefix": {
            "property": ["externalId"],
            "value": "1"
        }
    }
}

​
Highlights

When you enable highlights for your search query, the response contains an additional highlight field for each search hit, including the highlighted fragments for your query matches. However, the result limit is 20 documents due to the operation costs.

​
Filtering

Filtering uses a special JSON filtering language. It’s quite flexible and consists of a number of different “leaf” filters, which can be combined arbitrarily using the boolean clauses and, or, and not.

​
Supported leaf filters

Only includes results that are equal to the specified value. Supported fields: Non-array type fields.
{
    "equals": {
        "property": ["property"],
        "value": "example"
    }
}
Only includes results that are equal to one of the specified values. Supported fields: Non-array type fields.
{
    "in": {
        "property": ["property"],
        "values": [1, 2, 3]
    }
}
Only includes results which contain all of the specified values. Supported fields: Array type fields.
{
    "containsAll": {
        "property": ["property"],
        "values": [1, 2, 3]
    }
}
Only includes results which contain any of the specified values. Supported fields: Array type fields.
{
    "containsAny": {
        "property": ["property"],
        "values": [1, 2, 3]
    }
}
Only includes results where the specified property exists (has value). Supported fields: All fields.
{
    "exists": {
        "property": ["property"]
    }
}
Only includes results which start with the specified value. Supported fields: String type fields.
{
    "prefix": {
        "property": ["property"],
        "value": "example"
    }
}
Only includes results that fall within the specified range. Supported fields: Non-array type fields. Supported operators: gt, lt, gte, lte.
{
    "range": {
        "property": ["property"],
        "gt": 1,
        "lte": 5
    }
}
Only includes results where the geoshape intersects with the specified geometry. Supported fields: geoLocation.
{
    "geojsonIntersects": {
        "property": ["sourceFile", "geoLocation"],
        "geometry": {
            "type": "Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]]
        }
    }
}
Only includes results where the geoshape has nothing in common with the specified geometry. Supported fields: geoLocation.
{
    "geojsonDisjoint": {
        "property": ["sourceFile", "geoLocation"],
        "geometry": {
            "type": "Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]]
        }
    }
}
Only includes results where the geoshape falls within the specified geometry. Supported fields: geoLocation.
{
    "geojsonWithin": {
        "property": ["sourceFile", "geoLocation"],
        "geometry": {
            "type": "Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]]
        }
    }
}
Only includes results with a related asset in a subtree rooted at any specified IDs. Supported fields: assetIds, assetExternalIds.
{
    "filter": {
        "inAssetSubtree": {
            "property": ["sourceFile", "assetIds"],
            "values": [1, 2, 3]
        }
    }
}

​
Properties

The following overview shows the properties you can filter and which filter applies to which property.
PropertyTypeApplicable filters
["id"]integerequals, in, range, exists
["externalId"]stringequals, in, prefix, exists
["instanceId"]stringequals, in
["instanceId", "space"]stringequals, in, prefix, exists
["instanceId", "externalId"]stringequals, in, prefix, exists
["title"]stringequals, in, prefix, exists
["author"]stringequals, in, prefix, exists
["createdTime"]integerequals, in, range, exists
["modifiedTime"]integerequals, in, range, exists
["lastIndexedTime"]integerequals, in, range, exists
["mimeType"]stringequals, in, prefix, exists
["extension"]stringequals, in, prefix, exists
["pageCount"]integerequals, in, range, exists
["type"]stringequals, in, prefix, exists
["geoLocation"]geometry objectgeojsonIntersects, geojsonDisjoint, geojsonWithin, exists
["language"]stringequals, in, prefix, exists
["assetIds"]array of integerscontainsAny, containsAll, exists, inAssetSubtree
["assetExternalIds"]array of stringscontainsAny, containsAll, exists, inAssetSubtree
["labels"]array of LabelscontainsAny, containsAll, exists
["content"]stringsearch
["sourceFile", "name"]stringequals, in, prefix, exists, search
["sourceFile", "mimeType"]stringequals, in, prefix, exists
["sourceFile", "size"]integerequals, in, range, exists
["sourceFile", "source"]stringequals, in, prefix, exists
["sourceFile", "directory"]stringequals, in, prefix, exists
["sourceFile", "assetIds"]array of integerscontainsAny, containsAll, exists, inAssetSubtree
["sourceFile", "assetExternalIds"]array of stringscontainsAny, containsAll, exists, inAssetSubtree
["sourceFile", "datasetId"]integerequals, in, range, exists
["sourceFile", "securityCategories"]array of integerscontainsAny, containsAll, exists
["sourceFile", "labels"]array of LabelscontainsAny, containsAll, exists
["sourceFile", "metadata", <key>]stringequals, in, prefix, exists
["sourceFile", "metadata"]stringequals, in, prefix, exists
The ["sourceFile", "metadata"] property is a special filter field that targets all metadata values. It is an alternative to creating a filter for each key in the metadata field.

​
Full example

{
    "filter": {
        "and": [
            {
                "or": [
                    {
                        "equals": {
                            "property": ["type"],
                            "value": "PDF"
                        }
                    },
                    {
                        "prefix": {
                            "property": ["externalId"],
                            "value": "hello"
                        }
                    }
                ]
            },
            {
                "range": {
                    "property": ["createdTime"],
                    "lte": 1519862400000
                }
            },
            {
                "not": {
                    "in": {
                        "property": ["sourceFile", "name"],
                        "values": ["My Document.doc", "My Other Document.docx"]
                    }
                }
            }
        ]
    }
}

​
Sorting

By default, search results are ordered by relevance, meaning how well they match the given query string. However, it’s possible to specify a different property to sort by. Sorting can be ascending or descending. The sort order is ascending if none is specified.

​
Properties

The following overview shows all properties that can be sorted on.
Property
["id"]
["externalId"]
["mimeType"]
["extension"]
["pageCount"]
["author"]
["title"]
["language"]
["type"]
["createdTime"]
["modifiedTime"]
["lastIndexedTime"]
["sourceFile", "name"]
["sourceFile", "mimeType"]
["sourceFile", "size"]
["sourceFile", "source"]
["sourceFile", "datasetId"]
["sourceFile", "metadata", *]

​
Example

{
    "sort": [
        {
            "property": ["createdTime"],
            "order": "asc"
        }
    ]
}
Last modified on April 23, 2026