# AI-Powered Beekeeping Automation

> Connect your AI agent (Claude, ChatGPT, LLM bots) to b.tree beekeeping software via a secure API. Automate hive management, inspections, and data analysis.

## b.tree Agent API — Let AI Manage Your Hives

The b.tree **Agent API** is a dedicated endpoint that lets external **AI agents** and **LLM-powered assistants** (Claude, ChatGPT, custom bots, ClawBot, MCP-compatible agents) interact with your beekeeping data programmatically. Think of it as giving your AI assistant its own set of beekeeping tools.

Whether you're using **Claude Desktop**, **ChatGPT with custom actions**, a **Zapier AI workflow**, or building your own agent — b.tree provides full read and write access to your beekeeping operation through the secure Agent API (OpenAPI), with MCP available as an alternative.

---

### Why Use the Agent API?

- **Natural Language Beekeeping** — Ask your AI to "create a feeding record for all hives in the forest apiary" and it just works
- **Automation** — Build workflows that automatically log inspections, schedule treatments, or analyse harvest data
- **Multi-Tool Access** — Your AI agent gets access to 40+ tools: create/read/update/delete for feeds, treatments, harvests, checkups, todos, stock movements (charges), statistics, weather, and more, plus a read-only queen list with birth dates (for example to find colonies with a queen from 2024)
- **OpenAPI Discovery** — Your agent can auto-discover all available endpoints and their schemas
- **Secure** — API keys are SHA-256 hashed, per-user, with optional expiry dates

---

### Getting Started

#### 1. Generate an Agent Key

Navigate to **Settings → Profile → [Agent Keys](https://app.btree.at/setting/profile/agent-keys)** in your b.tree account.

Click **"Create Agent Key"** and optionally set:

- A **label** (e.g. "Claude Desktop", "My Automation")
- An **expiry date** (leave empty for permanent access)

⚠️ **Important**: The API key is only displayed once after creation. Copy it immediately and store it securely. It cannot be retrieved later.

Your key will look like: `btree_ak_a1B2c3D4e5F6g7H8i9J0...`

#### 2. Authenticate

Include your key in the `Authorization` header of every request:

```bash
Authorization: Bearer btree_ak_your_key_here
```

#### 3. Discover Available Tools

Fetch the full OpenAPI specification to see all available endpoints and their parameters:

```bash
GET https://api.btree.at/api/v1/agent/openapi.json
Authorization: Bearer btree_ak_your_key_here
```

This returns an **OpenAPI 3.1** spec that any compatible agent or tool can parse automatically.

#### 4. Call Tools

Each tool is available as a POST endpoint:

```bash
POST https://api.btree.at/api/v1/agent/tools/{toolName}
Authorization: Bearer btree_ak_your_key_here
Content-Type: application/json

{ ... parameters as JSON ... }
```

Example — list your apiaries and hives:

```json
POST /api/v1/agent/tools/listApiariesHives
{ "includeInactive": false }
```

---

### Result Size and Paging

A tool result is at most **60,000 characters** of JSON (about 60 KB for Latin-script data). `fetchTasks` and `fetchCharges` return records in pages that fit into this limit:

- `sort`: `newest` (default) or `oldest`. Records are ordered by date, then id.
- `format`: `compact` (default) returns flat records with ids and names, for example `hive_id`, `hive_name`, `apiary_name` and `type_name`. `csv` returns the same records as one CSV string. `full` returns the records with the nested hive, type, apiary, creator and editor objects.
- `limit`: optional, at most 1000. Without `limit`, the server fills the page up to the limit.
- The result contains `total`, `count`, `hasMore` and `nextCursor`. While `hasMore` is true, send the same request again with `cursor` set to `nextCursor`.

Example — all treatments since August, page by page:

```json
POST /api/v1/agent/tools/fetchTasks
{ "task": "treatment", "dateStart": "2026-08-01", "dateEnd": "2026-11-10" }
```

For the last feeding, use `{ "task": "feed", "sort": "newest", "limit": 1, "dateEnd": "" }`. To resolve `bee_id` and `edit_id` to company members, call `listCompanyUsers`.

`fetchCharges` (warehouse stock movements) also accepts `q`, `dateStart`, `dateEnd` and `includeDeleted`. Every page contains `stockSummary` with the current stock per stock item.

`fetchWaxLedger` returns two lists, `lots` and `operations`. Each list has `total`, `count`, `hasMore` and `nextCursor`. The first call also returns `productSummary` over all matching lots. Send the `nextCursor` of one list as `cursor` to get the next page of that list only.

`listMovements`, `listQueens` and `listApiariesHives` also return pages with `total`, `count`, `hasMore`, `nextCursor` and `items`:

- `listMovements` (hive movements) accepts `sort`, `format` and `limit` like `fetchTasks`. `dateStart` and `dateEnd` each work alone; `dateEnd` includes the whole day.
- `listQueens` orders the queens by birth date, then id. Queens without a birth date come first.
- `listApiariesHives` orders the apiaries by id. Each apiary contains its active hives.

---

### Rate Limits

The Agent API is rate-limited to **60 requests per minute** per API key. This is generous for interactive AI use and automation, but prevents abuse.

If you exceed the limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating when you can resume.

---

### Security Best Practices

- **Rotate keys regularly** — Create new keys and delete old ones periodically
- **Use expiry dates** — Set `valid_to` when you know the key should only be active temporarily
- **Label your keys** — Name them after the agent or service using them for easy tracking
- **Monitor last used** — Check the "Last Used" timestamp in your key list to identify stale keys
- **Delete unused keys** — If an agent is no longer in use, revoke its key immediately

Keys are **hashed with SHA-256 + unique salt** before storage. Even in the unlikely event of a database breach, your plaintext keys cannot be recovered.

When your account or company is deleted, all associated agent keys are automatically removed.

---

### Setting Up Your AI Agent or Skill

On the Agent Keys page in b.tree, you'll find a ready-to-use **skill installation prompt**. Copy it and paste it into your AI agent or skill editor. The prompt teaches it:

- How to authenticate with the b.tree API
- How to discover available tools via OpenAPI
- The b.tree data model conventions
- Best practices for creating and updating records

#### Install b.tree as a Custom Skill

Instead of creating a custom GPT or building your own agent, you can turn the installation prompt into a reusable skill on a supported AI platform:

- [ChatGPT Skills editor](https://chatgpt.com/skills/editor)
- [Kimi Skills](https://www.kimi.com/skills)
- [Claude skill creator](https://claude.ai/new?q=Let%27s+create+a+skill+together+using+your+skill-creator+skill.+First+ask+me+what+the+skill+should+do.)

Open your preferred skill editor, then copy the **skill installation prompt** from the b.tree Agent Keys page and paste it into the editor. Follow the platform's instructions to create the skill.

> **Alternative:** If you use ChatGPT, you can also try the ready-made b.tree custom GPT with OAuth login: [b.tree Beekeeping Manager EN](https://chatgpt.com/g/g-6a07eef786548191a55f6487827f9e5a-b-tree-beekeeping-manager-en) or [b.tree Imkerei Manager DE](https://chatgpt.com/g/g-6a2bcc6afba881918b2d6f35d920d7c2-b-tree-imkerei-manager-de).

---

### Use Cases

- **Voice-Controlled Beekeeping** — "Hey Claude, log a feeding of 3:2 sugar syrup for all hives in the meadow apiary"
- **Automated Reports** — Have your agent generate weekly summaries of treatments and inspections
- **Recurring Tasks** — Set up agents to create seasonal feeding or treatment schedules
- **Weather-Aware Management** — Agents can check apiary weather before suggesting actions
- **Multi-Platform** — Works with any AI agent that supports HTTP tool calls

---

### Alternative: MCP

For ChatGPT, Claude, VS Code, and other clients that support remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers, MCP is an alternative connection option. It exposes the same tools used by WizBee through Streamable HTTP and uses OAuth login — no API key needs to be copied into the AI client.

#### Connect an MCP client

1. Open **Settings → Profile → [MCP](https://app.btree.at/setting/profile/mcp)** in b.tree.
2. Copy the MCP server URL shown for your selected b.tree region.
3. Add it as a **remote MCP server** in your AI client.
4. Your browser opens b.tree. Sign in, review the requested access, and approve it.
5. Return to your AI client and start using the b.tree tools.

For the EU region, the server URL is:

```text
https://api.btree.at/api/v1/mcp
```

The MCP connection uses the company and role active when you approve it. Read-only users cannot use write tools. MCP access is a Premium feature and can be revoked at any time under **Settings → Profile → MCP**.

#### Example: Claude

b.tree is listed as a connector in the [Claude directory](https://claude.ai/directory/btree). On a paid Claude plan, open **Customize → Connectors** in Claude, select **+**, search for **b.tree**, and select **Connect**. Then sign in to b.tree and approve the access.

Once connected, ask Claude to list your apiaries, record a feeding for all hives of an apiary, or compare your harvests.

#### Example: Mistral AI

If you prefer a European AI provider, you can use **Mistral AI** to manage your beekeeping operation through b.tree MCP. Open [Connections in Le Chat](https://chat.mistral.ai/connections), add the b.tree MCP server URL shown above, and follow the b.tree OAuth login to approve access.

Once connected, ask Mistral to list your apiaries, record a feeding, or review your latest inspections.

The Agent API described above is the recommended starting point for automation with OpenAPI or direct HTTP calls. Agent API authentication uses a manually generated key.

---

_The Agent API is a Premium feature. [Upgrade your account](https://app.btree.at/premium) to get started._
