> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# KeepHQ

> Connect self-hosted KeepHQ to review stored alerts, incidents, workflows, and topology with an API key.

Connect self-hosted KeepHQ so CloudThinker can review stored alerts, incidents, workflow runs, and service topology using an API key.

> [!NOTE]
>
> KeepHQ availability is limited; if it is missing from **Builtin Connections**, ask your workspace administrator about access.

## Prerequisites

* A self-hosted Keep instance and permission to create API keys.
* An HTTPS route from CloudThinker to your Keep backend. For CloudThinker Cloud, see [Reaching private services](https://docs.cloudthinker.io/guide/connections/overview.md#reaching-private-services). For a [self-hosted deployment of CloudThinker](https://docs.cloudthinker.io/guide/deployment/overview.md), allow access from your deployment.
* The **Admin** role in your CloudThinker workspace. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md).

Opening Keep at `localhost` or through your SSH tunnel does not make its API reachable from CloudThinker. For disposable testing, a temporary public HTTPS tunnel can forward to the authenticated API; remove it afterward.

## Setup

**1. Identify the backend address**

Find your Keep API's HTTPS origin, such as `https://keep-api.example.com`. This can differ from the UI address. Include a port if required, but no UI path or `/alerts`.

**2. Create a dedicated API key**

In Keep, open **Settings → API Keys** and create a key. Enter a **Name**, such as `cloudthinker`, and select a **Role** covering the [required permissions](#required-permissions). Click **Create API Key** and copy the key.

Available roles depend on your [Keep authentication setup](https://docs.keephq.dev/deployment/authentication/overview); ask your Keep administrator for the narrowest suitable role.

**3. Add the connection in CloudThinker**

Open **More → Workspace settings → Connections**, stay on **Builtin Connections**, and select **KeepHQ**. Enter **API URL** and **API key**. Leave **CA certificate (optional)** empty for publicly trusted HTTPS; otherwise paste your private CA certificate in PEM format.

Click **Connect**. CloudThinker reads a small sample of stored alerts through Keep's REST API with `X-API-KEY` authentication.

**Success state:** KeepHQ shows a **Connected** status. This verifies alert access only; run the verification prompt below to check the other reads.

## Connection details

| Field | Description | Example |
| - | - | - |
| **API URL** | HTTPS backend origin, without a path, query, or embedded credentials | `https://keep-api.example.com` |
| **API key** | Dedicated Keep API key | Copy from **Settings → API Keys** |
| **CA certificate (optional)** | Private certificate authority certificate in PEM format; empty uses public trust | Leave empty for publicly trusted HTTPS |

Certificate and hostname verification always remain on. CloudThinker refuses redirects, so enter the exact backend origin rather than an address that redirects to it.

## Required permissions

The key's role must cover these [Keep API permissions](https://github.com/keephq/keep/tree/ab394bf49813b92377bbce4332d4f5cad1563a9c/keep/api/routes):

| Permission | Used for |
| - | - |
| `read:alert` | Stored alerts, alert history, and incident listings |
| `read:incident` | Individual incident details |
| `read:incidents` | An incident's linked alerts and workflow executions |
| `read:workflows` | Workflow metadata and execution status |
| `read:topology` | Stored services, applications, and dependencies |
| `write:topology` | Optional manual topology changes |

> [!TIP]
>
> Start with the five read permissions. Add `write:topology` only for topology changes, enable **Allow writes** on the connection, and review changes through [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md).

## Agent capabilities

| Capability | What CloudThinker can do | Approval |
| - | - | - |
| **Alerts** | Review stored occurrences and a selected alert's history | No |
| **Incidents** | Read details, linked alerts, and associated workflow executions | No |
| **Workflow health** | Inspect metadata, run history, and execution status without running workflows | No |
| **Topology** | Read stored services, applications, and dependencies | No |
| **Manual topology changes** | Create, update, or delete manual services, applications, and dependencies; preserve provider-managed services | Through Approvals |

The connection does not pull fresh data from providers, change incidents, execute workflows, or administer providers. Topology describes stored relationships, not live network reachability. Results are limited samples; alert counts describe returned occurrences, not all alerts.

### Verify the connection

```text theme={null}
Run KeepHQ discovery and summarize stored alerts, incidents, workflows, and topology; identify any area this key cannot read
```

Expect a sample or summary for each area. An unavailable area means a failed read, not an empty or healthy service.

### Example prompts

```text theme={null}
Review the returned KeepHQ alerts and show the history of the most severe one
List KeepHQ incidents and investigate one with its linked alerts and workflow executions
Summarize KeepHQ topology and identify services with no stored dependencies
```

## Troubleshooting

> [accordion] API key rejected
>
> Create a replacement key and update **API key** in the connection.

> [accordion] Missing alert permission
>
> The key's role lacks alert access. Other failed reads need their matching permissions from the table above.

> [accordion] Wrong API address
>
> Check **API URL** points to the backend, not the UI, and remove any path. A redirect also fails: use the final HTTPS origin directly.

> [accordion] Certificate verification failed
>
> Check the certificate matches the API hostname. For a private issuer, paste its CA certificate into **CA certificate (optional)**. If PEM is rejected, copy the complete certificate, including its BEGIN and END lines.

> [accordion] API unreachable
>
> Check DNS, firewall rules, and the route from CloudThinker to the API host and port. Access through your browser or local SSH tunnel alone is insufficient.

> [accordion] Rate limit reached
>
> Wait before reconnecting or repeating the request.

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- Keep API authentication enabled, including behind a testing tunnel, and restrict network access to CloudThinker where possible.
- After a topology write times out or cannot be verified, inspect current topology before retrying to avoid repeating a change.

## Related

> [card] [Connections](https://docs.cloudthinker.io/guide/connections/overview.md)
>
> Manage credentials and reach private services.

> [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md)
>
> Control which topology changes can run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.