# Kiteworks API — cards Operations

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

**Summary:** Get list of cards

### Description:
  Returns the list of admin dashboard cards filtered by the specified card types.
### Precondition:
  The user must be an administrator.
### Response:
  Returns the list of cards matching the specified types.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `type:in` | query | yes | Comma-separated list of card types to retrieve. `content_encryption` – Content encryption card. `email_json_migration` – Email JSON migration card. `system_security_scanning` – System security scanning card. `events_table_monitor` – Events table monitor card. `appadmin_db` – Application admin database card. `sysadmin_db` – System admin database card. `sysadmin_hosts` – System admin hosts card. `epg_warnings` – EPG warnings card. `safe_edit_server_health` – Safe edit server health card. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The list of cards has 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_USER |
| 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_ACCESS_USER):**

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

**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/admin/cards?type:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

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

---

## GET /rest/admin/cards/details

**Summary:** Get card details

### Description:
  Returns the detailed information for a specific admin dashboard card.
### Precondition:
  The user must be an administrator with System or Application role.
### Response:
  Returns the details of the specified card.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `type` | query | yes | The type of card to retrieve details for. `content_encryption` – Content encryption card. `email_json_migration` – Email JSON migration card. `system_security_scanning` – System security scanning card. `events_table_monitor` – Events table monitor card. `appadmin_db` – Application admin database card. `sysadmin_db` – System admin database card. `sysadmin_hosts` – System admin hosts card. `epg_warnings` – EPG warnings card. `safe_edit_server_health` – Safe edit server health card. |
| `hostId` | query | no | The unique identifier of the host to filter card data by. |
| `volume` | query | no | Filter results to a specific storage volume. |
| `storageType` | query | no | Filter results by storage type. `user_files` – User file storage. `replication_files` – Replication file storage. |
| `limit` | query | no | Maximum number of error detail records to return. Error details are not returned if not set or set to 0. |
| `offset` | query | no | Number of error detail records to skip before returning results, for pagination. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The card details 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_USER |
| 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_ACCESS_USER):**

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

**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/admin/cards/details?type=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

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

---

## POST /rest/admin/cards/actions

**Summary:** Perform an action on a card

### Description:
  Submits an action to perform on a specific admin dashboard card.
### Precondition:
  The user must be an administrator with System or Application role.
### Response:
  The action has been accepted and will be processed.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `action` | string | yes | The action to perform on the card. `retry` – Retry the failed operation. `delete` – Delete the card or related records. |
| `type` | string | yes | The type of card to perform the action on. `content_encryption` – Content encryption card. `email_json_migration` – Email JSON migration card. `system_security_scanning` – System security scanning card. `events_table_monitor` – Events table monitor card. `appadmin_db` – Application admin database card. `sysadmin_db` – System admin database card. `sysadmin_hosts` – System admin hosts card. `epg_warnings` – EPG warnings card. `safe_edit_server_health` – Safe edit server health card. |
| `hostId` | string | no | The unique identifier of the host associated with the card. |
| `storageType` | string | no | The storage type for the files to process. `user_files` – User file storage. `replication_files` – Replication file storage. |
| `volume` | string | no | The storage volume containing the files to process. |
| `fileId` | integer[] | no | List of file IDs to retry content encryption for. |
| `emailId` | integer[] | no | List of email IDs to retry migrating to JSON format. |

**Responses:**

| Code | Description |
|------|-------------|
| 202 | The action has been accepted and is being processed. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 404 | Not Found  <i>Possible error codes: </i>ERR_ENTITY_NOT_FOUND |
| 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_ACCESS_USER):**

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

**404 (ERR_ENTITY_NOT_FOUND):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_NOT_FOUND",
      "message": "Entity does not exist"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/admin/cards/actions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "action": "retry",
         "type": "content_encryption",
         "hostId": "string",
         "storageType": "string",
         "volume": "string",
         "fileId": [
         1
       ]
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/cards/actions"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "action": "retry",
  "type": "content_encryption",
  "hostId": "string",
  "storageType": "string",
  "volume": "string",
  "fileId": [
  1
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---