# Plugins

<a id="get-api-v1-plugins"></a>
#### `GET /api/v1/plugins`

*List plugins*

List all available plugins with their current status.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_dict_str__Any___` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    {}
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins
```

---

<a id="get-api-v1-plugins-sidebar-entries"></a>
#### `GET /api/v1/plugins/sidebar-entries`

*Plugin sidebar entries*

Return sidebar entries declared by active plugins, scoped to the caller's role.

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `audience` | string | no | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_dict_str__Any___` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": [
    {}
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/sidebar-entries
```

---

<a id="get-api-v1-plugins-tasks"></a>
#### `GET /api/v1/plugins/tasks`

*Active plugin tasks*

Return snapshots of every plugin task still running (resume support for the UI).

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_dict_str__Any___` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    {}
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/tasks
```

---

<a id="get-api-v1-plugins-tasks-task-id"></a>
#### `GET /api/v1/plugins/tasks/{task_id}`

*Plugin task snapshot*

Polling fallback — returns a full snapshot of a plugin task.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `task_id` | string | yes | pattern=`^[a-f0-9]{8,64}$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/tasks/{task_id}
```

---

<a id="get-api-v1-plugins-tasks-task-id-events"></a>
#### `GET /api/v1/plugins/tasks/{task_id}/events`

*Stream Plugin Task Events*

Server-Sent Events stream for a plugin task.

authenticated session can't saturate the agent's thread pool by
rapidly reopening EventSource subscriptions. The actual stream is
held open for the task's lifetime and the client reads events as
they occur.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `task_id` | string | yes | pattern=`^[a-f0-9]{8,64}$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | — | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/tasks/{task_id}/events
```

---

<a id="get-api-v1-plugins-plugin-id"></a>
#### `GET /api/v1/plugins/{plugin_id}`

*Get plugin*

Get details of a specific plugin.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `plugin_id` | string | yes | pattern=`^[a-z][a-z0-9_-]{1,30}$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/{plugin_id}
```

---

<a id="post-api-v1-plugins-plugin-id-activate"></a>
#### `POST /api/v1/plugins/{plugin_id}/activate`

*Activate plugin (blocking)*

Activate a plugin with trial or license mode; blocks for the full install duration.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `plugin_id` | string | yes | pattern=`^[a-z][a-z0-9_-]{1,30}$` |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `mode` | string | no | Activation mode: 'trial', 'license', or 'free'; default `free` |
| `serial_key` | string | no | License serial key (required when mode is 'license') |

**Request body example:**

```json
{
  "mode": "free",
  "serial_key": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/plugins/{plugin_id}/activate
```

---

<a id="post-api-v1-plugins-plugin-id-activate-async"></a>
#### `POST /api/v1/plugins/{plugin_id}/activate/async`

*Activate plugin (async)*

Kick off plugin activation in the background; returns a task_id for SSE subscription.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `plugin_id` | string | yes | pattern=`^[a-z][a-z0-9_-]{1,30}$` |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `mode` | string | no | Activation mode: 'trial', 'license', or 'free'; default `free` |
| `serial_key` | string | no | License serial key (required when mode is 'license') |

**Request body example:**

```json
{
  "mode": "free",
  "serial_key": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/plugins/{plugin_id}/activate/async
```

---

<a id="post-api-v1-plugins-plugin-id-deactivate"></a>
#### `POST /api/v1/plugins/{plugin_id}/deactivate`

*Deactivate plugin*

Deactivate a plugin and revert to default state.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `plugin_id` | string | yes | pattern=`^[a-z][a-z0-9_-]{1,30}$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/{plugin_id}/deactivate
```

---

<a id="post-api-v1-plugins-plugin-id-reset-state"></a>
#### `POST /api/v1/plugins/{plugin_id}/reset-state`

*Reset plugin state*

Force-reset a plugin's state record to idle (use when an interrupted pipeline left a stuck marker).

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `plugin_id` | string | yes | pattern=`^[a-z][a-z0-9_-]{1,30}$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/{plugin_id}/reset-state
```

---

<a id="post-api-v1-plugins-plugin-id-update"></a>
#### `POST /api/v1/plugins/{plugin_id}/update`

*Update plugin*

Update an active plugin to the latest version.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `plugin_id` | string | yes | pattern=`^[a-z][a-z0-9_-]{1,30}$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/plugins/{plugin_id}/update
```

---