From c1079da753977712d99067a02052a245696ba722 Mon Sep 17 00:00:00 2001 From: Hynek Urban Date: Mon, 2 Mar 2026 09:07:22 +0100 Subject: [PATCH 1/3] Add a guide for connecting AI agents. --- content/docs/guides/connecting-agents.mdx | 75 +++++++++++++++++++++++ content/docs/guides/meta.json | 4 +- 2 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 content/docs/guides/connecting-agents.mdx diff --git a/content/docs/guides/connecting-agents.mdx b/content/docs/guides/connecting-agents.mdx new file mode 100644 index 0000000..c0f8fda --- /dev/null +++ b/content/docs/guides/connecting-agents.mdx @@ -0,0 +1,75 @@ +--- +title: Connecting AI agents +--- + +# Connect AI Agents to the Umami API + +If you'd like to connect an AI agent to the Umami API, for example to help you analyze the events, this guide shows you how. + + +## 1. Install the Prerequisites + +On the machine where the agent will run, we'll install the +Latchkey tool. That will allow the agent to send authenticated +HTTP requests to the API without leaking any secrets to prompts. + +1. Make sure your system has a working `node` installation. If not, you can download it from the [official page](https://nodejs.org/en/download). +2. Install Latchkey: + + ```bash + npm install -g latchkey + ``` + +## 2. Generate and Configure the API Token + +1. Follow the [authentication docs](../api/authentication) to obtain an API token or key. +2. Point Latchkey to your instance, for example: + + ```bash + latchkey services register my-umami \ + --service-family umami \ + --base-api-url=http://203.0.113.1:8000/api/v1 + ``` + + (This step is not necessary for Umami Cloud.) + +3. Insert the API token: + + ```bash + latchkey auth set my-umami -H "Authorization: Bearer " + ``` + +## 3. Configure the AI Agent + +Using `skills.sh`: + +```bash +npx skills add imbue-ai/latchkey +``` + +You can also configure the AI agent manually. The exact steps +will differ depending on the agent. Taking OpenCode as an example: + +```bash +mkdir -p ~/.opencode/skills/latchkey +latchkey skill-md > ~/.opencode/skills/latchkey/SKILL.md +``` + + +## 4. Use the AI Agent + +After completing the previous steps, you should now be able to +use your AI agent of choice to work with Umami! Here are some +example questions and tasks for the agent: + +> Which referrer sends the highest-quality traffic (with the highest average session duration)? + +or + +> What does my audience look like on weekends vs. weekdays? + +or even just + +> Tell me what's working on our blog and what isn't. + +From here, it's up to your imagination. diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json index 7114755..b66ea4f 100644 --- a/content/docs/guides/meta.json +++ b/content/docs/guides/meta.json @@ -25,7 +25,9 @@ "running-on-railway", "running-on-sevalla", "running-on-supabase", - "running-on-vercel" + "running-on-vercel", + "---AI---", + "connecting-agents" ], "defaultOpen": true } From 00cd896cdbf066bcf4feb9f4301f98e5cd5756de Mon Sep 17 00:00:00 2001 From: Hynek Urban Date: Mon, 2 Mar 2026 13:07:15 +0100 Subject: [PATCH 2/3] Fix the guide with respect to Umami Cloud. --- content/docs/guides/connecting-agents.mdx | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/content/docs/guides/connecting-agents.mdx b/content/docs/guides/connecting-agents.mdx index c0f8fda..22786ac 100644 --- a/content/docs/guides/connecting-agents.mdx +++ b/content/docs/guides/connecting-agents.mdx @@ -22,26 +22,31 @@ HTTP requests to the API without leaking any secrets to prompts. ## 2. Generate and Configure the API Token -1. Follow the [authentication docs](../api/authentication) to obtain an API token or key. -2. Point Latchkey to your instance, for example: +1. Follow the [authentication docs](../api/authentication) to obtain an API token or an API key. +2. If you don't use Umami Cloud, point Latchkey to your instance. For example: ```bash latchkey services register my-umami \ --service-family umami \ - --base-api-url=http://203.0.113.1:8000/api/v1 + --base-api-url=http://203.0.113.1:3000/api/ ``` - (This step is not necessary for Umami Cloud.) - 3. Insert the API token: ```bash latchkey auth set my-umami -H "Authorization: Bearer " ``` + Alternatively, for Umami Cloud: + + ```bash + latchkey auth set umami -H "x-umami-api-key: " + ``` + + ## 3. Configure the AI Agent -Using `skills.sh`: +Using [skills.sh](https://skills.sh/): ```bash npx skills add imbue-ai/latchkey @@ -68,7 +73,7 @@ or > What does my audience look like on weekends vs. weekdays? -or even just +or even > Tell me what's working on our blog and what isn't. From 81d6a02bf28c4901cd07f0e11176997b83578e43 Mon Sep 17 00:00:00 2001 From: Hynek Urban Date: Mon, 2 Mar 2026 13:23:41 +0100 Subject: [PATCH 3/3] Avoid duplicating the header. --- content/docs/guides/connecting-agents.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/content/docs/guides/connecting-agents.mdx b/content/docs/guides/connecting-agents.mdx index 22786ac..f85ebca 100644 --- a/content/docs/guides/connecting-agents.mdx +++ b/content/docs/guides/connecting-agents.mdx @@ -1,9 +1,7 @@ --- -title: Connecting AI agents +title: Connecting AI agents to the API --- -# Connect AI Agents to the Umami API - If you'd like to connect an AI agent to the Umami API, for example to help you analyze the events, this guide shows you how.