# Kiteworks API — sources Operations

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

**Summary:** Return user's sources

### Description:
  Returns a list of sources available to the current user, such as external cloud storage or SharePoint connections.
### Precondition:
  User must be authenticated and have access to at least one source.
### Response:
  A list of the user's sources is returned.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `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 | The user's sources 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_ACCESS_DENIED, ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS |
| 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_ACCESS_DENIED):**

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

**403 (ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_USER_HAS_INSUFFICIENT_PERMISSIONS",
      "message": "Target user has insufficient access permissions"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/sources

**Summary:** Add user ECM source

Creates a new ECM source for the current user with the provided name, URL, and source type. Returns 422 if a source with the same name or URL already exists for this 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 |
|----------|------|----------|-------------|
| `name` | string | yes | Display name of the source |
| `description` | string | no | Optional description of the source providing additional context about its contents or purpose |
| `sourceUrl` | string | yes | URL of the external source system to connect to |
| `sourceTypeId` | string | yes | Unique identifier of source type |
| `username` | string | no | Username for authenticating with the external source system |
| `password` | string | no | Password for authenticating with the external source system |
| `repository` | string | no | Name of the repository within the external source system to connect to |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**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/sources" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "name": "string",
         "description": "string",
         "sourceUrl": "string",
         "sourceTypeId": "string",
         "username": "string",
         "password": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/sources"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "name": "string",
  "description": "string",
  "sourceUrl": "string",
  "sourceTypeId": "string",
  "username": "string",
  "password": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## PATCH /rest/sources/actions/lock

**Summary:** Lock Repositories Gateway files

Locks one or more Repositories Gateway files. Supports partial success — if some files cannot be locked, the operation continues for the remaining files.

**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 |
|------|-------------|
| 200 | Files locked successfully. |
| 490 | Request blocked by WAF |

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## PATCH /rest/sources/actions/unlock

**Summary:** Unlock Repositories Gateway files

Unlocks one or more Repositories Gateway files. Supports partial success — if some files cannot be unlocked, the operation continues for the remaining files.

**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 |
|------|-------------|
| 200 | Files unlocked successfully. |
| 490 | Request blocked by WAF |

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/sources/auth

**Summary:** Login to cloud source

Completes the cloud ECM authentication flow by submitting the code and state values returned by the ECM provider's redirect URL. Returns 200 on success or an error if the credentials are invalid.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `client` | string | no | ID of the client, from redirect url |
| `code` | string | yes | Code from redirect url |
| `state` | string | yes | Anti-CSRF state token returned by the OAuth provider in the redirect URL |
| `sessionState` | string | no | Optional field needed for SharePoint Online and OneDrive |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Cloud ECM authentication completed successfully. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**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/sources/auth" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "client": "string",
         "code": "string",
         "state": "string",
         "sessionState": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/sources/auth"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "client": "string",
  "code": "string",
  "state": "string",
  "sessionState": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/sources/files/actions/transferStatus

**Summary:** Get kp transfer status.

Returns the status of one or more file transfer operations to Repositories Gateway, including transaction ID, file name, user ID, error code, transfer status, and AV/DLP scan results.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `transactionId` | query | no | Transaction ID of download |
| `transactionId:in` | query | no | Transaction ID of download. Search for results that match any of the specified values for this parameter. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Transfer status records retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TransferStatusList):**

```json
{
  "data": [
    {
      "id": 1,
      "transactionId": "txn-001",
      "kpObjectId": "e0000001",
      "fileName": "contract.docx",
      "userId": 42,
      "errorCode": null,
      "status": "completed"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

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

**Summary:** Get info of an Repositories Gateway file.

Returns the details of the specified Repositories Gateway file, including its name, parent ID, type, timestamps, and the current user's permissions on it.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of Repositories Gateway file |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Repositories Gateway file details retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (SourceFileInfo):**

```json
{
  "id": "e0000001",
  "name": "contract-2024.docx",
  "parentId": "f0000001",
  "type": "file",
  "created": "2024-02-15T10:00:00+00:00",
  "modified": "2024-03-05T08:00:00+00:00",
  "deleted": false
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of Repositories Gateway file

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

---

## DELETE /rest/sources/files/{id}

**Summary:** Delete an Repositories Gateway file.

Permanently deletes the specified Repositories Gateway file. When the `forceDelete` query parameter is set to true, the file can be deleted even if it is currently in use by the requesting user. Deleting a file in use by another user is not permitted.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of Repositories Gateway file |
| `forceDelete` | query | no | If set to true, allows the user to delete a file that is only in their own use. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Repositories Gateway file deleted successfully. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_FILE_IS_IN_USE_BY_OTHER_USER, ERR_FILE_IS_IN_USE_BY_CURRENT_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**422 (ERR_FILE_IS_IN_USE_BY_OTHER_USER):**

```json
{
  "errors": {
    "code": "ERR_FILE_IS_IN_USE_BY_OTHER_USER",
    "message": "Repositories Gateway file is used by other user"
  }
}
```

**422 (ERR_FILE_IS_IN_USE_BY_CURRENT_USER):**

```json
{
  "errors": {
    "code": "ERR_FILE_IS_IN_USE_BY_CURRENT_USER",
    "message": "Repositories Gateway file is used by you"
  }
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of Repositories Gateway file

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

---

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

**Summary:** Get info of an Repositories Gateway folder.

Returns the details of the specified Repositories Gateway folder, including its name, parent, type, timestamps, and child counts.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of Repositories Gateway folder |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Repositories Gateway folder details retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (SourceFolderInfo):**

```json
{
  "id": "f0000001",
  "name": "Contracts",
  "parentId": "s0000001",
  "type": "directory",
  "created": "2024-01-10T09:00:00+00:00",
  "modified": "2024-03-01T14:30:00+00:00",
  "totalFilesCount": 5,
  "totalFoldersCount": 2
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of Repositories Gateway folder

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

---

## DELETE /rest/sources/folders/{id}

**Summary:** Delete an Repositories Gateway folder.

Permanently deletes the specified Repositories Gateway folder.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of Repositories Gateway folder |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Repositories Gateway folder deleted successfully. |
| 490 | Request blocked by WAF |

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of Repositories Gateway folder

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

---

## GET /rest/sources/{id}

**Summary:** Returns requested ECM source

Returns the details of the specified ECM source, including its name, description, URL, source type, pinned status, and the current user's permissions on it.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the source to be retrieved |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | ECM source details retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (SourceInfo):**

```json
{
  "id": "s0000001",
  "name": "SharePoint Docs",
  "description": "Corporate SharePoint",
  "sourceUrl": "https://sharepoint.example.com",
  "sourceTypeId": 2,
  "pinned": false,
  "pinnedTime": null
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the source to be retrieved

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

---

## DELETE /rest/sources/{id}

**Summary:** Deletes specified source

Removes the specified ECM source from the current user's source list.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the source to be deleted. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | ECM source deleted 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/sources/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the source to be deleted.

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

---

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

**Summary:** Get url with redirect to cloud ECM auth

Returns the authentication redirect URL and client ID for the specified cloud ECM source. The caller should redirect the user to the returned URL to complete the authentication flow with the ECM provider.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The source ID |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Cloud ECM authentication URL retrieved successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (EcmAuthRedirect):**

```json
{
  "redirect": "https://ecm.example.com/auth/login",
  "clientId": "abc123"
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # The source ID

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

---

## POST /rest/sources/{id}/auth

**Summary:** Login to on-premise source

Authenticates the current user to the specified on-premise ECM source using a login and password. Returns 200 on success or an error if the credentials are invalid.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The source ID |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `login` | string | yes | Login |
| `password` | string | yes | Password |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | On-premise ECM authentication completed successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

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

**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/sources/:id/auth" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "login": "string",
         "password": "string"
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # The source ID

url = f"https://{{instance}}.kiteworks.com/rest/sources/{id}/auth"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "login": "string",
  "password": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

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

**Summary:** Get cloud ECM auth status

Checks whether the current user is authenticated to the specified cloud ECM source by attempting to list its contents. Returns HTTP 200 if authenticated, or an error if authentication is required.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The source ID |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | User is authenticated to the cloud ECM source. |
| 490 | Request blocked by WAF |

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # The source ID

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

---

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

**Summary:** Returns the content of the specified ECM source

Returns a paginated list of both files and subfolders within the specified ECM source folder, including each item's name, parent ID, type, timestamps, and permissions.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the source folder to be retrieved |
| `name` | query | no | Object name |
| `name:contains` | query | no | Object name. Search for results that contain the specified characters in this parameter. |
| `description` | query | no | Object description |
| `description:contains` | query | no | Object description. Search for results that contain the specified characters in this parameter. |
| `created` | query | no | Object creation date |
| `created:gt` | query | no | Object creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Object creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Object creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Object creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | Object modification date |
| `modified:gt` | query | no | Object modification date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Object modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Object modification date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Object modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Indicates that object is deleted |
| `type` | query | no | Filter by object type. Accepted values: `f`, `d`. |
| `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 | ECM source folder contents retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ChildrenList):**

```json
{
  "data": [
    {
      "id": "f0000001",
      "name": "Contracts",
      "parentId": "s0000001",
      "type": "directory"
    },
    {
      "id": "e0000001",
      "name": "overview.pdf",
      "parentId": "s0000001",
      "type": "file"
    }
  ],
  "metadata": {
    "total": 2,
    "limit": 50,
    "offset": 0
  }
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the source folder to be retrieved

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

---

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

**Summary:** Get access token for external file edit.

Returns a short-lived refresh token (expires after 300 seconds) scoped to the specified Repositories Gateway file, enabling an external editor to download and re-upload the file.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the file |
| `name` | query | no | Object name |
| `name:contains` | query | no | Object name. Search for results that contain the specified characters in this parameter. |
| `userId` | query | no | Unique identifier of Object creator |
| `userId:in` | query | no | Unique identifier of Object creator. Search for results that match any of the specified values for this parameter. |
| `created` | query | no | Object creation date |
| `created:gt` | query | no | Object creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Object creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Object creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Object creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | Object modification date |
| `modified:gt` | query | no | Object modification date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Object modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Object modification date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Object modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Indicates whether the object is deleted. |
| `expire` | query | no | Expiration date |
| `expire:gt` | query | no | Expiration date. Search for results where this parameter value is greater than the specified value. |
| `expire:gte` | query | no | Expiration date. Search for results where this parameter value is greater than or equal to the specified value. |
| `expire:lt` | query | no | Expiration date. Search for results where this parameter value is less than the specified value. |
| `expire:lte` | query | no | Expiration date. Search for results where this parameter value is less than or equal to the specified value. |
| `isPushed` | query | no | Whether the file is pushed |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `locate_id` | query | no | If specified, "offset" parameter will be ignored                                             and the page containing entity with this Id will be returned. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Refresh token for external file edit returned successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (RefreshTokenList):**

```json
{
  "data": [
    {
      "refreshToken": "abc123def456",
      "scope": "POST/sources/actions/files/e0000001 GET/sources/files/e0000001",
      "expires": "2024-03-20T12:05:00+00:00"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the file

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

---

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

**Summary:** Returns the list of folders of the specified ECM folder

Returns a paginated list of subfolders within the specified ECM source folder, including each folder's name, parent ID, type, timestamps, and permissions.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the source folder to be retrieved |
| `name` | query | no | Object name |
| `name:contains` | query | no | Object name. Search for results that contain the specified characters in this parameter. |
| `description` | query | no | Object description |
| `description:contains` | query | no | Object description. Search for results that contain the specified characters in this parameter. |
| `created` | query | no | Object creation date |
| `created:gt` | query | no | Object creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Object creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Object creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Object creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | Object modification date |
| `modified:gt` | query | no | Object modification date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Object modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Object modification date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Object modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Indicates that object is deleted |
| `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 | ECM folder contents retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (FolderList):**

```json
{
  "data": [
    {
      "id": "f0000001",
      "name": "Contracts",
      "parentId": "s0000001",
      "type": "directory",
      "created": "2024-01-10T09:00:00+00:00",
      "modified": "2024-03-01T14:30:00+00:00"
    }
  ],
  "metadata": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the source folder to be retrieved

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

---

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

**Summary:** Get file preview metadata for a file in Repositories Gateway source

Gets the current preview generation status for the specified file in a Repositories Gateway
                       source. When the preview is ready, the response includes the MIME type and a link to retrieve
                       it. If the file is empty, infected, or DLP-locked, an appropriate error status is returned
                       instead.

**Requires `view` permission on the file.**

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the file from Repositories Gateway Source. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the current preview status for the file. When `status` is `ready`, the `mime` and `link` fields are populated. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (PreviewReady):**

```json
{
  "status": "ready",
  "mime": "application/pdf",
  "link": "/preview/file/kp-42"
}
```

**200 (PreviewProcessing):**

```json
{
  "status": "processing",
  "mime": null,
  "link": null
}
```

**200 (PreviewFailed):**

```json
{
  "status": "failed",
  "mime": null,
  "link": null
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # The unique identifier of the file from Repositories Gateway Source.

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

---

## GET /rest/sources/{parent}/files

**Summary:** Returns the list of files of the specified ECM folder

Returns a paginated list of files within the specified ECM source folder, including each file's name, parent ID, type, timestamps, and permissions.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `parent` | path | yes | ID of the source folder to be retrieved |
| `name` | query | no | Object name |
| `name:contains` | query | no | Object name. Search for results that contain the specified characters in this parameter. |
| `description` | query | no | Object description |
| `description:contains` | query | no | Object description. Search for results that contain the specified characters in this parameter. |
| `created` | query | no | Object creation date |
| `created:gt` | query | no | Object creation date. Search for results where this parameter value is greater than the specified value. |
| `created:gte` | query | no | Object creation date. Search for results where this parameter value is greater than or equal to the specified value. |
| `created:lt` | query | no | Object creation date. Search for results where this parameter value is less than the specified value. |
| `created:lte` | query | no | Object creation date. Search for results where this parameter value is less than or equal to the specified value. |
| `modified` | query | no | Object modification date |
| `modified:gt` | query | no | Object modification date. Search for results where this parameter value is greater than the specified value. |
| `modified:gte` | query | no | Object modification date. Search for results where this parameter value is greater than or equal to the specified value. |
| `modified:lt` | query | no | Object modification date. Search for results where this parameter value is less than the specified value. |
| `modified:lte` | query | no | Object modification date. Search for results where this parameter value is less than or equal to the specified value. |
| `deleted` | query | no | Indicates that object is deleted |
| `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 | ECM folder file listing retrieved successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (FileList):**

```json
{
  "data": [
    {
      "id": "e0000001",
      "name": "contract-2024.docx",
      "parentId": "f0000001",
      "type": "file",
      "created": "2024-02-15T10:00:00+00:00",
      "modified": "2024-03-05T08:00:00+00:00"
    }
  ],
  "metadata": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

parent = "VALUE"  # ID of the source folder to be retrieved

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

---