# Kiteworks API — favorites Operations

**5 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/favorites.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/favorites.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/favorites

**Summary:** List favorites

### Description:
  Returns the list of favorites for the current user.
### Precondition:
  User must be authenticated.
### Response:
  The list of favorited files and folders is returned.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
| `parentId` | query | no | Filter favorites by parent folder ID. |
| `parentId:in` | query | no | Filter favorites by parent folder ID. Search for results that contain any of the specified values. |
| `excludeEc` | query | no | If set to `true`, excludes Repositories Gateway folders from the results. |
| `orderBy` | query | no | Sort order for the results. Default is `objects.created:asc`. Allowed values: `objects.name:asc`, `objects.name:desc`, `objects.created:asc`, `objects.created:desc`, `objects.modified:asc`, `objects.modified:desc`. |
| `limit` | query | no | Range limit. |
| `offset` | query | no | Range offset. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The list of favorites has been successfully returned. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_DENIED |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_ACCESS_USER):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_USER",
      "message": "Insufficient access permissions"
    }
  ]
}
```

**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_ACCESS_DENIED):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_DENIED",
      "message": "Your access is denied.",
      "redirectUrl": "/login?code=3317"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/favorites

**Summary:** Add a favorite

Marks the specified folder as a favorite for the current user.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `objectId` | integer | yes | Unique identifier of the favorited folder or file |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Favorite created successfully. |
| 409 | Conflict  <i>Possible error codes: </i>ERR_ENTITY_EXISTS |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (FavoriteCreated):**

```json
{
  "id": 42,
  "objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
  "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890"
}
```

**409 (ERR_ENTITY_EXISTS):**

```json
{
  "errors": {
    "code": "ERR_ENTITY_EXISTS",
    "message": "Entity exists"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": {
    "code": "ERR_INPUT_REQUIRED",
    "message": "Field is required"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/favorites" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "objectId": 1,
         "addLinks": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/favorites"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "objectId": 1,
  "addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/favorites/{id}

**Summary:** Remove a favorite

Removes the specified favorite from the current user's favorites list.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the favorite to be removed |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Favorite removed successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the favorite to be removed

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

---

## POST /rest/folders/actions/favorite

**Summary:** Set multiple folders as favorite

Marks multiple folders as favorites for the current user in a single request. Supports partial success, meaning valid items are processed even if some fail.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Favorites created successfully. |
| 409 | Conflict  <i>Possible error codes: </i>ERR_ENTITY_EXISTS |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (BulkFavoriteCreated):**

```json
{
  "data": [
    {
      "id": 42,
      "objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
      "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890"
    },
    {
      "id": 43,
      "objectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890"
    }
  ]
}
```

**409 (ERR_ENTITY_EXISTS):**

```json
{
  "errors": {
    "code": "ERR_ENTITY_EXISTS",
    "message": "Entity exists"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/folders/actions/favorite?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/folders/actions/favorite"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "id:in": "VALUE",
}
response = requests.post(url, params=params, headers=headers)
print(response.json())
```

---

## DELETE /rest/folders/actions/favorite

**Summary:** Removes specified folders from favorites

Removes multiple folders from the current user's favorites list in a single request. Supports partial success, meaning valid items are processed even if some fail.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Favorites removed successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/folders/actions/favorite?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/folders/actions/favorite"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())
```

---