# Kiteworks API — search Operations

**3 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/search.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/search.json)

> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.

---

## GET /rest/search

**Summary:** Return lists of files/folders/emails from search results

Searches across files, folders, and emails using the provided query. Returns matching results grouped by type, along with total counts and a flag indicating whether full-text search is enabled.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `objectId` | query | no | Id of folder to search |
| `content` | query | no | Search by content |
| `content:contains` | query | no | Search by content. Search for results that contain the specified characters in this parameter. |
| `content:startswith` | query | no |  |
| `description` | query | no | Search by description |
| `description:contains` | query | no | Search by description. Search for results that contain the specified characters in this parameter. |
| `description:startswith` | query | no |  |
| `user` | query | no | Search by user |
| `modified` | query | no | Search by modified date |
| `modified:gt` | query | no | Search by modified date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Search by modified date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Search by modified date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Search by modified date. Search for results where this parameter value is less than or equal to the specified value. |
| `created` | query | no | Search by created date |
| `created:gt` | query | no | Search by created date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Search by created date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Search by created date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Search by created date. Search for results where this parameter value is less than or equal to the specified value. |
| `locked` | query | no | Search by lock status |
| `locked:gt` | query | no | Search by lock status. Search for results where this parameter value is greater than the specified value. |
| `locked:gte` | query | no | Search by lock status. Search for results where this parameter value is greater than or equal to the specified value. |
| `locked:lt` | query | no | Search by lock status. Search for results where this parameter value is less than the specified value. |
| `locked:lte` | query | no | Search by lock status. Search for results where this parameter value is less than or equal to the specified value. |
| `filesize` | query | no | Search by file size |
| `filesize:gt` | query | no | Search by file size. Search for results where this parameter value is greater than the specified value. |
| `filesize:gte` | query | no | Search by file size. Search for results where this parameter value is greater than or equal to the specified value. |
| `filesize:lt` | query | no | Search by file size. Search for results where this parameter value is less than the specified value. |
| `filesize:lte` | query | no | Search by file size. Search for results where this parameter value is less than or equal to the specified value. |
| `file_type` | query | no | Search by file type. Accepted values: `Documents`, `Spreadsheets`, `Presentations`, `Images`, `PDF`, `Multimedia`, `Text`. |
| `email_type` | query | no | Search by email type. Accepted values: `Inbox`, `Draft`, `Sent`. |
| `tracking_id` | query | no | Search files by tracking ID (UUID) |
| `tracking_id:eq` | query | no |  |
| `path` | query | no | Search files/folders by path. If this is specified, other search criteria is no longer valid. |
| `path:contains` | query | no | Search files/folders by path. If this is specified, other search criteria is no longer valid.. Search for results that contain the specified characters in this parameter. |
| `searchType` | query | no | Search by object type. Accepted values: `f`, `d`, `m`, `k`. |
| `searchFilter` | query | no | Scope of the search. Accepted values: `all`, `shared`. |
| `fls_only` | query | no | Search only files shared to me. |
| `sharedMailboxId` | query | no | Id of shared mailbox to search |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Search results retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (SearchResults):**

```json
{
  "id": "contract",
  "fullTextSearch": true,
  "files": [
    {
      "id": 7,
      "name": "contract-2024.pdf"
    }
  ],
  "folders": [],
  "emails": [],
  "metadata": {
    "files": 1,
    "folders": 0,
    "emails": 0
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/search" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/search"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/sources/{id}/query

**Summary:** Search SharePoint sites

### Description:
  Searches for SharePoint sites accessible through the specified source connection.
### Precondition:
  User must have a valid SharePoint Online source connection configured.
### Response:
  Returns a list of matching SharePoint sites.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the entity. |
| `include_kw` | query | no | If true, includes Kiteworks native sources in the results. |
| `include_container` | query | no | If true, includes container-type sources (e.g. SharePoint document libraries) in the results. |
| `limit` | query | no | Maximum number of results to return. |
| `offset` | query | no | Number of results to skip before returning results, for pagination. |
| `query` | query | no | Search query string to filter sources or sites by name. |
| `search_type` | query | no | Type of search to perform against the source. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | SharePoint sites have been successfully returned. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_AUTH_EC_UPDATE_TOKEN, ERR_SPO_SEARCH |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_AUTH_INVALID_CSRF):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_INVALID_CSRF",
      "message": "Invalid CSRF Authentication"
    }
  ]
}
```

**401 (ERR_AUTH_UNAUTHORIZED):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_UNAUTHORIZED",
      "message": "Unauthorized"
    }
  ]
}
```

**403 (ERR_AUTH_EC_UPDATE_TOKEN):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_EC_UPDATE_TOKEN",
      "message": "Token update/receive required"
    }
  ]
}
```

**403 (ERR_SPO_SEARCH):**

```json
{
  "errors": [
    {
      "code": "ERR_SPO_SEARCH",
      "message": "Unable to call SPO Search API"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/sources/:id/query" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier of the entity.

url = f"https://{{instance}}.kiteworks.com/rest/sources/{id}/query"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## GET /rest/query

**Summary:** Perform a search query

### Description:
  Searches for files, folders, or emails based on the provided query parameters.
### Precondition:
  The user must be authenticated.
### Response:
  Returns a list of matching files, folders, or emails.
### Sorting:
  Sorting can be applied using two query parameters: `orderBy` for the field name,
  and `orderType` for the sort order, which can be either `asc` or `desc`.
### Sorting options:
  | FIELD_NAME | Description |
  |------------|-------------|
  | score      | The search relevance score |
  | name       | The name of the folder or file |
  | created    | The creation datetime of the folder or file |
  | modified   | The last modified datetime of the folder or file |

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |
| `includeContent` | query | yes | Indicates whether it is a full-text search or a database search. |
| `searchType` | query | yes | Comma-separated list of object types to search. `f` – Files. `d` – Folders. `e` – Emails. |
| `query` | query | no | Search query string. |
| `objectId` | query | no | Search within a specific folder ID. |
| `created` | query | no | Exact creation date. |
| `created:gt` | query | no | Created after the specified date. |
| `created:gte` | query | no | Created on or after the specified date. |
| `created:lt` | query | no | Created before the specified date. |
| `created:lte` | query | no | Created on or before the specified date. |
| `modified` | query | no | Exact modified date. |
| `modified:gt` | query | no | Modified after the specified date. |
| `modified:gte` | query | no | Modified on or after the specified date. |
| `modified:lt` | query | no | Modified before the specified date. |
| `modified:lte` | query | no | Modified on or before the specified date. |
| `fileSize` | query | no | Exact file size in bytes. |
| `fileSize:gt` | query | no | File size greater than the specified value. |
| `fileSize:gte` | query | no | File size greater than or equal to the specified value. |
| `fileSize:lt` | query | no | File size less than the specified value. |
| `fileSize:lte` | query | no | File size less than or equal to the specified value. |
| `user` | query | no | User email of the folder creator. |
| `fileType` | query | no | List of comma-separated file types to filter search results. |
| `flsOnly` | query | no | If true, only includes files shared with the user. |
| `sharedMailboxId` | query | no | Shared mailbox ID. |
| `orderBy` | query | no | Field to sort results by. Allowed values: `score`, `name`, `created`, `modified`. |
| `orderType` | query | no | Sort direction for the results. `asc` – Ascending order. `desc` – Descending order. |
| `nameOnly` | query | no | If true, searches only for file/folder names. |
| `subject` | query | no | Email subject filter. |
| `senderId` | query | no | Sender ID. |
| `recipientId` | query | no | Recipient ID. |
| `fileName` | query | no | File name filter. |
| `folderName` | query | no | Folder name filter. |
| `fileContent` | query | no | Search within file content. |
| `spellCheck` | query | no | If true, provides spelling suggestions for the search query. |
| `bucket` | query | no | Filter email search results by mailbox folder. `inbox` – Search in the inbox. `sent` – Search in sent items. |
| `path` | query | no | Search within a specific folder path. |
| `tracking_id` | query | no | Filter files by their tracking ID (UUID). |
| `extensions` | query | no | Comma-separated file extensions to filter (e.g., "pdf,form" or ".pdf,.form"). |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Search completed successfully. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_PROFILE_COLLABORATION_DISABLED |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_AUTH_INVALID_CSRF):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_INVALID_CSRF",
      "message": "Invalid CSRF Authentication"
    }
  ]
}
```

**401 (ERR_AUTH_UNAUTHORIZED):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_UNAUTHORIZED",
      "message": "Unauthorized"
    }
  ]
}
```

**403 (ERR_PROFILE_COLLABORATION_DISABLED):**

```json
{
  "errors": [
    {
      "code": "ERR_PROFILE_COLLABORATION_DISABLED",
      "message": "User's profile has no collaboration access"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

```json
{
  "errors": [
    {
      "code": "ERR_INVALID_PARAMETER",
      "message": "Invalid Parameter Exception"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/query?includeContent=VALUE&searchType=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/query"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "includeContent": "VALUE",
    "searchType": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())
```

---