Kibana

---
name: kibana
description: "Kibana API integration with managed authentication. Manage saved objects, dashboards, data views, spaces, alerts, and fleet.\n Use this skill when users want to interact with Kibana for observability, security, and search analytics.\n For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway)."
---

# Kibana

Access Kibana saved objects, dashboards, data views, spaces, alerts, and fleet via managed API authentication.

## Quick Start

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/kibana/api/saved_objects/_find?type=dashboard')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('kbn-xsrf', 'true')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/kibana/{native-api-path}
```

The gateway proxies requests to your Kibana instance and automatically injects authentication.

## Authentication

All requests require the Maton API key and the `kbn-xsrf` header:

```
Authorization: Bearer $MATON_API_KEY
kbn-xsrf: true
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Kibana connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=kibana&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'kibana'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

Open the returned `url` in a browser to complete authentication. You'll need to provide your Kibana API key.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

---

## API Reference

**Important:** All Kibana API requests require the `kbn-xsrf: true` header.

### Status & Features

#### Get Status

```bash
GET /kibana/api/status
```

**Response:**
```json
{
  "name": "kibana",
  "uuid": "abc123",
  "version": {
    "number": "8.15.0",
    "build_hash": "..."
  },
  "status": {
    "overall": {"level": "available"}
  }
}
```

#### List Features

```bash
GET /kibana/api/features
```

Returns list of all Kibana features and their capabilities.

---

### Saved Objects

#### Find Saved Objects

```bash
GET /kibana/api/saved_objects/_find?type={type}
```

**Query Parameters:**
- `type` - Object type: `dashboard`, `visualization`, `index-pattern`, `search`, `lens`, `map`
- `search` - Search query
- `page` - Page number
- `per_page` - Results per page (default 20, max 10000)
- `fields` - Fields to return

**Response:**
```json
{
  "page": 1,
  "per_page": 20,
  "total": 5,
  "saved_objects": [
    {
      "id": "abc123",
      "type": "dashboard",
      "attributes": {
        "title": "My Dashboard",
        "description": "Dashboard description"
      },
      "version": "1",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

#### Get Saved Object

```bash
GET /kibana/api/saved_objects/{type}/{id}
```

#### Create Saved Object

```bash
POST /kibana/api/saved_objects/{type}/{id}
Content-Type: application/json

{
  "attributes": {
    "title": "My Index Pattern",
    "timeFieldName": "@timestamp"
  }
}
```

#### Update Saved Object

```bash
PUT /kibana/api/saved_objects/{type}/{id}
Content-Type: application/json

{
  "attributes": {
    "title": "Updated Title"
  }
}
```

#### Delete Saved Object

```bash
DELETE /kibana/api/saved_objects/{type}/{id}
```

#### Bulk Operations

```bash
POST /kibana/api/saved_objects/_bulk_get
Content-Type: application/json

[
  {"type": "dashboard", "id": "abc123"},
  {"type": "visualization", "id": "def456"}
]
```

---

### Data Views

#### List Data Views

```bash
GET /kibana/api/data_views
```

**Response:**
```json
{
  "data_view": [
    {
      "id": "abc123",
      "title": "logs-*",
      "timeFieldName": "@timestamp"
    }
  ]
}
```

#### Get Data View

```bash
GET /kibana/api/data_views/data_view/{id}
```

#### Create Data View

```bash
POST /kibana/api/data_views/data_view
Content-Type: application/json

{
  "data_view": {
    "title": "logs-*",
    "timeFieldName": "@timestamp"
  }
}
```

**Response:**
```json
{
  "data_view": {
    "id": "abc123",
    "title": "logs-*",
    "timeFieldName": "@timestamp"
  }
}
```

#### Update Data View

```bash
POST /kibana/api/data_views/data_view/{id}
Content-Type: application/json

{
  "data_view": {
    "title": "updated-logs-*"
  }
}
```

#### Delete Data View

```bash
DELETE /kibana/api/data_views/data_view/{id}
```

---

### Spaces

#### List Spaces

```bash
GET /kibana/api/spaces/space
```

**Response:**
```json
[
  {
    "id": "default",
    "name": "Default",
    "description": "Default space",
    "disabledFeatures": []
  }
]
```

#### Get Space

```bash
GET /kibana/api/spaces/space/{id}
```

#### Create Space

```bash
POST /kibana/api/spaces/space
Content-Type: application/json

{
  "id": "marketing",
  "name": "Marketing",
  "description": "Marketing team space",
  "disabledFeatures": []
}
```

#### Update Space

```bash
PUT /kibana/api/spaces/space/{id}
Content-Type: application/json

{
  "id": "marketing",
  "name": "Marketing Team",
  "description": "Updated description"
}
```

#### Delete Space

```bash
DELETE /kibana/api/spaces/space/{id}
```

---

### Alerting

#### Find Alert Rules

```bash
GET /kibana/api/alerting/rules/_find
```

**Query Parameters:**
- `search` - Search query
- `page` - Page number
- `per_page` - Results per page

**Response:**
```json
{
  "page": 1,
  "per_page": 10,
  "total": 5,
  "data": [
    {
      "id": "abc123",
      "name": "CPU Alert",
      "consumer": "alerts",
      "enabled": true,
      "rule_type_id": "metrics.alert.threshold"
    }
  ]
}
```

#### Get Alert Rule

```bash
GET /kibana/api/alerting/rule/{id}
```

#### Enable/Disable Rule

```bash
POST /kibana/api/alerting/rule/{id}/_enable
POST /kibana/api/alerting/rule/{id}/_disable
```

#### Mute/Unmute Rule

```bash
POST /kibana/api/alerting/rule/{id}/_mute_all
POST /kibana/api/alerting/rule/{id}/_unmute_all
```

#### Get Alerting Health

```bash
GET /kibana/api/alerting/_health
```

---

### Connectors (Actions)

#### List Connectors

```bash
GET /kibana/api/actions/connectors
```

**Response:**
```json
[
  {
    "id": "abc123",
    "name": "Email Connector",
    "connector_type_id": ".email",
    "is_preconfigured": false,
    "is_deprecated": false
  }
]
```

#### Get Connector

```bash
GET /kibana/api/actions/connector/{id}
```

#### List Connector Types

```bash
GET /kibana/api/actions/connector_types
```

#### Execute Connector

```bash
POST /kibana/api/actions/connector/{id}/_execute
Content-Type: application/json

{
  "params": {
    "to": ["user@example.com"],
    "subject": "Alert",
    "message": "Alert triggered"
  }
}
```

---

### Fleet

#### List Agent Policies

```bash
GET /kibana/api/fleet/agent_policies
```

**Response:**
```json
{
  "items": [
    {
      "id": "abc123",
      "name": "Default policy",
      "namespace": "default",
      "status": "active"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 20
}
```

#### List Agents

```bash
GET /kibana/api/fleet/agents
```

#### List Packages

```bash
GET /kibana/api/fleet/epm/packages
```

Returns all available integrations/packages.

---

### Security

#### List Roles

```bash
GET /kibana/api/security/role
```

**Response:**
```json
[
  {
    "name": "admin",
    "metadata": {},
    "elasticsearch": {
      "cluster": ["all"],
      "indices": [...]
    },
    "kibana": [...]
  }
]
```

#### Get Role

```bash
GET /kibana/api/security/role/{name}
```

---

### Cases

#### Find Cases

```bash
GET /kibana/api/cases/_find
```

**Query Parameters:**
- `status` - `open`, `in-progress`, `closed`
- `severity` - `low`, `medium`, `high`, `critical`
- `page` - Page number
- `perPage` - Results per page

**Response:**
```json
{
  "cases": [],
  "page": 1,
  "per_page": 20,
  "total": 0
}
```

---

## Code Examples

### JavaScript

```javascript
const response = await fetch('https://gateway.maton.ai/kibana/api/saved_objects/_find?type=dashboard', {
  headers: {
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
    'kbn-xsrf': 'true'
  }
});
const dashboards = await response.json();
console.log(dashboards);
```

### Python

```python
import os
import requests

response = requests.get(
    'https://gateway.maton.ai/kibana/api/saved_objects/_find?type=dashboard',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'kbn-xsrf': 'true'
    }
)
print(response.json())
```

---

## Notes

- All requests require `kbn-xsrf: true` header
- Saved object types: `dashboard`, `visualization`, `index-pattern`, `search`, `lens`, `map`
- Data views are the modern replacement for index patterns
- Spaces provide multi-tenancy support
- Fleet manages Elastic Agents and integrations
- Some operations require specific Kibana privileges

## Error Handling

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 204 | No content (successful delete) |
| 400 | Invalid request |
| 401 | Invalid or missing authentication |
| 403 | Permission denied |
| 404 | Resource not found |
| 409 | Conflict (e.g., object already exists) |

## Resources

- [Kibana REST API Documentation](https://www.elastic.co/docs/api/doc/kibana/)
- [Saved Objects API](https://www.elastic.co/guide/en/kibana/current/saved-objects-api.html)
- [Alerting API](https://www.elastic.co/guide/en/kibana/current/alerting-apis.html)
- [Fleet API](https://www.elastic.co/guide/en/fleet/current/fleet-apis.html)
- [Maton Community](https://discord.com/invite/dBfFAcefs2)
- [Maton Support](mailto:support@maton.ai)