### Manual install with Bun

Source: https://hivekeep.app/docs/getting-started/installation

Performs a manual installation: clones the repo, installs dependencies with Bun, builds, runs database migrations, and starts in production mode.

```bash
git clone https://github.com/MarlBurroW/hivekeep.git
cd hivekeep
bun install
bun run build
bun run db:migrate
NODE_ENV=production bun run start

```

--------------------------------

### Install HiveKeep with curl

Source: https://hivekeep.app/docs

Run this command on Linux or macOS to install HiveKeep. It downloads and executes the install script, then opens the browser for guided setup. For custom ports, domains, or Docker, see the full install options.

```bash
$ curl -fsSL https://raw.githubusercontent.com/MarlBurroW/hivekeep/main/install.sh | bash
```

--------------------------------

### Install Hivekeep with one-liner script

Source: https://hivekeep.app/docs/getting-started/installation

Installs Hivekeep on Linux or macOS via a one-liner. The script installs Bun if missing, clones to /opt/hivekeep, builds, migrates, creates a system service, and starts on port 3000.

```bash
curl -fsSL https://raw.githubusercontent.com/MarlBurroW/hivekeep/main/install.sh | bash

```

--------------------------------

### GET /api/plugins

Source: https://hivekeep.app/docs/api/rest

Lists all installed plugins.

```APIDOC
## GET /api/plugins

### Description
Lists all installed plugins.

### Method
GET

### Endpoint
/api/plugins

```

--------------------------------

### Storage usage examples

Source: https://hivekeep.app/docs/plugins/api

Shows typical usage of the storage API: setting, getting, deleting, listing, and clearing keys.

```typescript
// Examples
await ctx.storage.set('lastSync', Date.now())
const lastSync = await ctx.storage.get<number>('lastSync')
await ctx.storage.delete('lastSync')
const keys = await ctx.storage.list('cache:')
await ctx.storage.clear()
```

--------------------------------

### Install plugin from npm

Source: https://hivekeep.app/docs/plugins/api

Installs a plugin from the npm registry by specifying the package name. Uses the endpoint POST /api/plugins/install with a JSON body.

```bash
curl -X POST http://localhost:3000/api/plugins/install \
  -H 'Content-Type: application/json' \
  -d '{"source": "npm", "package": "hivekeep-plugin-weather"}'
```

--------------------------------

### Responsive Grid Example with Tailwind-like Classes

Source: https://hivekeep.app/docs/mini-apps/sdk-reference

Example of a responsive grid layout using utility classes with breakpoints sm, md, lg, and xl.

```html
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
```

--------------------------------

### Install plugin from Git URL

Source: https://hivekeep.app/docs/plugins/api

Installs an unpublished or private plugin from a Git repository URL. Uses the endpoint POST /api/plugins/install with a JSON body.

```bash
curl -X POST http://localhost:3000/api/plugins/install \
  -H 'Content-Type: application/json' \
  -d '{"source": "git", "url": "https://github.com/user/hivekeep-plugin-weather"}'
```

--------------------------------

### Customize install with HIVEKEEP_DIR and HIVEKEEP_PORT

Source: https://hivekeep.app/docs/getting-started/installation

Customizes the one-liner install by setting the install directory, data directory, and port before running the script.

```bash
HIVEKEEP_DIR=/home/me/hivekeep \
HIVEKEEP_DATA_DIR=/home/me/hivekeep-data \
HIVEKEEP_PORT=8080 \
  bash <(curl -fsSL https://raw.githubusercontent.com/MarlBurroW/hivekeep/main/install.sh)

```

--------------------------------

### POST /api/plugins

Source: https://hivekeep.app/docs/api/rest

Installs a new plugin.

```APIDOC
## POST /api/plugins

### Description
Installs a new plugin.

### Method
POST

### Endpoint
/api/plugins

```

--------------------------------

### POST /api/version-check/update

Source: https://hivekeep.app/docs/api/rest

Starts the safe self-update process. Admin only, git installs. Returns a runId; progress is available via SSE and outcome in /last-update. Returns 400 for Docker/dev installs, 409 if already running.

```APIDOC
## POST /api/version-check/update

### Description
Start the safe self-update (admin only, git installs). Returns `{ runId }`; progress over SSE `update:progress`, outcome in `/last-update`. 400 for Docker/dev installs, 409 if already running.

### Method
POST

### Endpoint
/api/version-check/update

### Response
#### Success Response (200)
- **runId** (string) - The ID of the update run.

#### Response Example
{
  "runId": "string"
}

#### Error Response (400)
- **error** (string) - Error message for unsupported install types.

#### Error Response (409)
- **error** (string) - Error message if an update is already running.
```

--------------------------------

### Run Hivekeep with Docker

Source: https://hivekeep.app/docs/getting-started/installation

Runs Hivekeep in a container, mapping port 3000 and persisting data to a volume. After completion, open http://localhost:3000; the setup guide Queenie handles the rest.

```bash
docker run -d --name hivekeep \
  -p 3000:3000 \
  -v hivekeep-data:/app/data \
  ghcr.io/marlburrow/hivekeep:latest

```

--------------------------------

### List and get mini-apps with Hivekeep.apps

Source: https://hivekeep.app/docs/mini-apps/sdk-reference

Lists all mini-apps from the same Agent and gets details of a specific app. Returns an object with id, name, slug, description, icon, and version.

```javascript
await Hivekeep.apps.list()     // List all mini-apps from the same Agent
await Hivekeep.apps.get(appId) // Get details of a specific app
// Returns: { id, name, slug, description, icon, version }
```

--------------------------------

### Install plugin from git repository via API

Source: https://hivekeep.app/docs/plugins/tutorial-mistral

Installs the plugin directly from a git repository without publishing. This is an admin-only operation. The request body specifies the source as 'git' and the repository URL.

```bash
curl -X POST http://localhost:3000/api/plugins/install \
  -H 'Content-Type: application/json' \
  -d '{"source":"git","url":"https://github.com/your-name/hivekeep-plugin-mistral.git"}'
```

--------------------------------

### GET /api/mini-apps/:id/static/*

Source: https://hivekeep.app/docs/api/rest

Serves static assets for a mini-app.

```APIDOC
## GET /api/mini-apps/:id/static/*

### Description
Serve static assets.

### Method
GET

### Endpoint
/api/mini-apps/:id/static/*

### Parameters
#### Path Parameters
- **id** (string) - Required - The mini-app ID.
- **path** (string) - Required - The static asset path (wildcard).

```

--------------------------------

### Snapshot creation prompt

Source: https://hivekeep.app/docs/mini-apps/getting-started

An example prompt for creating a snapshot before making risky changes. The Agent calls create_mini_app_snapshot.

```text
"Create a snapshot of the todo app before the redesign"
```

--------------------------------

### Update Docker install with docker compose

Source: https://hivekeep.app/docs/getting-started/updating

Run this command to update a Docker install. The UI shows this command because a container cannot replace its own image.

```bash
docker compose pull && docker compose up -d
```

--------------------------------

### GET /api/agents/:id/context-preview

Source: https://hivekeep.app/docs/api/rest

Get full LLM context preview (system prompt, messages, tools, token estimates). Accepts ?taskId or ?sessionId query params.

```APIDOC
## GET /api/agents/:id/context-preview

### Description
Get full LLM context preview (system prompt, messages, tools, token estimates). Accepts ?taskId or ?sessionId query params.

### Method
GET

### Endpoint
/api/agents/:id/context-preview

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent ID

#### Query Parameters
- **taskId** (string) - Optional - Task ID
- **sessionId** (string) - Optional - Session ID

### Response
#### Success Response (200)
- **context** (object) - Full LLM context preview

#### Response Example
{
  "context": {}
}
```

--------------------------------

### GET /api/mini-apps/sdk/hivekeep-sdk.css

Source: https://hivekeep.app/docs/api/rest

Serves the SDK stylesheet.

```APIDOC
## GET /api/mini-apps/sdk/hivekeep-sdk.css

### Description
SDK stylesheet.

### Method
GET

### Endpoint
/api/mini-apps/sdk/hivekeep-sdk.css

```

--------------------------------

### Implement LLMProvider with Mistral example

Source: https://hivekeep.app/docs/plugins/developing

Complete example of an `LLMProvider` implementation. It defines the provider's `type`, `displayName`, `apiKeyUrl`, and `configSchema`, and implements `authenticate`, `listModels`, and the async generator `chat`. The `chat` method must stream text-delta, tool-use, thinking-delta, and thinking-signature chunks, and finish with exactly one finish chunk carrying `{ reason, usage }`.

```typescript
import type {
  LLMProvider,
  ChatRequest,
  ChatChunk,
  PluginContext,
} from '@hivekeep/sdk'


class MistralProvider implements LLMProvider {
  readonly type = 'mistral'
  readonly displayName = 'Mistral'
  readonly apiKeyUrl = 'https://console.mistral.ai/api-keys'
  readonly configSchema = [
    { key: 'apiKey', type: 'secret', label: 'API Key', required: true },
  ] as const


  async authenticate(config) {
    // validate the key, return { valid, error?, accountLabel? }
    return { valid: true }
  }


  async listModels(config) {
    // return [{ id, name, contextWindow, thinking?, supportsImageInput?, … }]
    return []
  }


  async *chat(model, request: ChatRequest, config): AsyncIterable<ChatChunk> {
    // stream text-delta / tool-use / thinking-delta / thinking-signature chunks,
    // finish with exactly one finish chunk carrying { reason, usage }
  }
}


export default function (ctx: PluginContext) {
  return { providers: [new MistralProvider()] }
}

```

--------------------------------

### Rollback prompt

Source: https://hivekeep.app/docs/mini-apps/getting-started

An example prompt for rolling back to a previous version. The Agent calls create_mini_app_snapshot to roll back.

```text
"Roll back the todo app to the previous version"
```

--------------------------------

### GET /api/mini-apps

Source: https://hivekeep.app/docs/api/rest

Lists all mini-apps.

```APIDOC
## GET /api/mini-apps

### Description
List all mini-apps.

### Method
GET

### Endpoint
/api/mini-apps

```

--------------------------------

### GET /api/mini-apps/sdk/*.d.ts

Source: https://hivekeep.app/docs/api/rest

Serves TypeScript declaration files for the SDK.

```APIDOC
## GET /api/mini-apps/sdk/*.d.ts

### Description
TypeScript declarations.

### Method
GET

### Endpoint
/api/mini-apps/sdk/*.d.ts

```

--------------------------------

### GET /api/mini-apps/:id/serve

Source: https://hivekeep.app/docs/api/rest

Serves the mini-app HTML.

```APIDOC
## GET /api/mini-apps/:id/serve

### Description
Serve mini-app HTML.

### Method
GET

### Endpoint
/api/mini-apps/:id/serve

### Parameters
#### Path Parameters
- **id** (string) - Required - The mini-app ID.

```

--------------------------------

### Frontend useApi example

Source: https://hivekeep.app/docs/mini-apps/getting-started

Shows how to access the backend from the frontend using useApi. It returns data and loading, and displays a spinner while loading.

```javascript
import { useApi } from "@hivekeep/react";


function Stats() {
  const { data, loading } = useApi("/stats");
  if (loading) return <Spinner />;
  return <p>Total keys: {data.totalKeys}</p>;
}
```

--------------------------------

### GET /api/mcp-servers

Source: https://hivekeep.app/docs/api/rest

Lists all MCP server configurations.

```APIDOC
## GET /api/mcp-servers

### Description
List MCP server configs.

### Method
GET

### Endpoint
/api/mcp-servers

### Response
#### Success Response (200)
- **mcpServers** (array) - List of MCP server configurations.

#### Response Example
{
  "mcpServers": []
}
```

--------------------------------

### Hand-written plugin entry point with greet tool

Source: https://hivekeep.app/docs/plugins/developing

Hand-written plugin entry point that exports a greet tool. Uses the SDK's tool and z helpers, declares availability for main and sub-agent, and logs on load. Requires a matching plugin.json manifest.

```typescript
import { tool, z } from '@hivekeep/sdk'
import type { PluginContext, PluginExports } from '@hivekeep/sdk'


export default function (ctx: PluginContext): PluginExports {
  ctx.log.info('hello-agent plugin loaded')


  return {
    tools: {
      greet: {
        availability: ['main', 'sub-agent'],
        create: () =>
          tool({
            description: 'Say hi to someone.',
            inputSchema: z.object({
              name: z.string().describe('Who to greet'),
            }),
            execute: async ({ name }) => ({
              reply: `Hi ${name}, glad to meet you!`,
            }),
          }),
      },
    },
  }
}

```

--------------------------------

### Mini-app creation flow diagram

Source: https://hivekeep.app/docs/mini-apps/overview

ASCII diagram showing the flow from user request to Agent calling create_mini_app, writing files, and updating storage.

```text
User asks Agent → Agent calls create_mini_app → App appears in sidebar
                Agent writes files          → App auto-reloads
                Agent updates storage       → App reflects changes
```

--------------------------------

### GET /api/mini-apps/:id/files

Source: https://hivekeep.app/docs/api/rest

Lists files for a mini-app.

```APIDOC
## GET /api/mini-apps/:id/files

### Description
List app files.

### Method
GET

### Endpoint
/api/mini-apps/:id/files

### Parameters
#### Path Parameters
- **id** (string) - Required - The mini-app ID.

```

--------------------------------

### GET /api/mini-apps/sdk/hivekeep-sdk.js

Source: https://hivekeep.app/docs/api/rest

Serves the Hivekeep SDK JavaScript file.

```APIDOC
## GET /api/mini-apps/sdk/hivekeep-sdk.js

### Description
SDK JavaScript.

### Method
GET

### Endpoint
/api/mini-apps/sdk/hivekeep-sdk.js

```

--------------------------------

### GET /api/mini-apps/sdk/hivekeep-react.js

Source: https://hivekeep.app/docs/api/rest

Serves the React bindings for the Hivekeep SDK.

```APIDOC
## GET /api/mini-apps/sdk/hivekeep-react.js

### Description
React bindings.

### Method
GET

### Endpoint
/api/mini-apps/sdk/hivekeep-react.js

```

--------------------------------

### GET /api/version-check

Source: https://hivekeep.app/docs/api/rest

Retrieves cached version information including current version, channel, installation type, latest version, changelog, and self-update capability.

```APIDOC
## GET /api/version-check

### Description
Cached version info: current version/sha, channel (`stable`/`edge`), installation type, latest version, cumulative changelog, `canSelfUpdate`.

### Method
GET

### Endpoint
/api/version-check

### Response
#### Success Response (200)
- **currentVersion** (string) - Current version.
- **currentSha** (string) - Current commit SHA.
- **channel** (string) - Update channel: `stable` or `edge`.
- **installationType** (string) - Installation type.
- **latestVersion** (string) - Latest available version.
- **changelog** (string) - Cumulative changelog.
- **canSelfUpdate** (boolean) - Whether self-update is possible.

#### Response Example
{
  "currentVersion": "string",
  "currentSha": "string",
  "channel": "stable",
  "installationType": "string",
  "latestVersion": "string",
  "changelog": "string",
  "canSelfUpdate": true
}
```

--------------------------------

### GET /api/plugins/registry/npm-search

Source: https://hivekeep.app/docs/plugins/api

Searches the public npm registry for packages tagged with the 'hivekeep-plugin' keyword. Results are tagged with an 'installed' boolean. Server-side cache is 5 minutes per query.

```APIDOC
## GET /api/plugins/registry/npm-search

### Description
Search the public npm registry for packages tagged with the `hivekeep-plugin` keyword.

### Method
GET

### Endpoint
/api/plugins/registry/npm-search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.

### Response
#### Success Response (200)
- **results** (array) - List of packages with `installed` boolean.

#### Response Example
```json
{
  "results": [
    {
      "name": "hivekeep-plugin-example",
      "installed": false
    }
  ]
}
```
```

--------------------------------

### GET /api/mini-apps/sdk/hivekeep-components.js

Source: https://hivekeep.app/docs/api/rest

Serves the component library for the Hivekeep SDK.

```APIDOC
## GET /api/mini-apps/sdk/hivekeep-components.js

### Description
Component library.

### Method
GET

### Endpoint
/api/mini-apps/sdk/hivekeep-components.js

```

--------------------------------

### POST /api/plugins/install

Source: https://hivekeep.app/docs/plugins/api

Installs a plugin from a git repository or npm package. The request body must specify the source type and the URL or package name.

```APIDOC
## POST /api/plugins/install

### Description
Install from git or npm.

### Method
POST

### Endpoint
/api/plugins/install

### Request Body
- **source** (string) - Required - The source type: 'git' or 'npm'.
- **url/package** (string) - Required - The git URL or npm package name.

### Request Example
```json
{
  "source": "npm",
  "url/package": "hivekeep-plugin-example"
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message.

#### Response Example
```json
{
  "status": "installed"
}
```
```

--------------------------------

### GET /api/notifications/unread-count

Source: https://hivekeep.app/docs/api/rest

Gets the number of unread notifications.

```APIDOC
## GET /api/notifications/unread-count

### Description
Get unread count.

### Method
GET

### Endpoint
/api/notifications/unread-count

### Parameters
No parameters documented.

### Response
#### Success Response (200)
- **count** (integer) - The number of unread notifications.

#### Response Example
{
  "count": 3
}

```

--------------------------------

### GET /api/vault/entries/:id

Source: https://hivekeep.app/docs/api/rest

Get details of a specific entry.

```APIDOC
## GET /api/vault/entries/:id

### Description
Get details of a specific entry.

### Method
GET

### Endpoint
/api/vault/entries/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The entry ID.

```

--------------------------------

### useApi(path, options?)

Source: https://hivekeep.app/docs/mini-apps/hooks

Fetches data from the mini-app's _server.js backend. Auto-fetches on mount and when path changes.

```APIDOC
## useApi(path, options?)

### Description
Fetches data from the mini-app's `_server.js` backend. Auto-fetches on mount and when `path` changes.

### Signature
`useApi(path, options?)`

### Parameters
- **path** (string) - Required - The API endpoint path.
- **options** (object) - Optional - Options object with properties:
  - **method** (string) - Optional - HTTP method.
  - **body** (any) - Optional - Request body.
  - **enabled** (boolean) - Optional - Whether to enable fetching.

### Returns
Returns an object with properties:
- **data** (any) - The fetched data.
- **loading** (boolean) - Whether the request is in progress.
- **error** (Error) - Any error that occurred.
- **refetch** (function) - Function to manually refetch.

### Example
```js
const { data, loading, error, refetch } = useApi("/items");
```
```

--------------------------------

### Template creation prompt

Source: https://hivekeep.app/docs/mini-apps/getting-started

An example prompt for creating a mini-app using a built-in template. Available templates include dashboard, todo-list, form, data-viewer, kanban, responsive, background-service, and contacts-manager.

```text
"Create a dashboard mini-app using the dashboard template"
```

--------------------------------

### GET /api/contacts/:id

Source: https://hivekeep.app/docs/api/rest

Gets details of a specific contact.

```APIDOC
## GET /api/contacts/:id

### Description
Gets details of a specific contact.

### Method
GET

### Endpoint
/api/contacts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the contact.

```

--------------------------------

### GET /api/mini-apps/:id

Source: https://hivekeep.app/docs/api/rest

Gets details of a specific mini-app.

```APIDOC
## GET /api/mini-apps/:id

### Description
Get mini-app details.

### Method
GET

### Endpoint
/api/mini-apps/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The mini-app ID.

```

--------------------------------

### GET /api/channels/pending-count

Source: https://hivekeep.app/docs/api/rest

Gets pending message counts for channels.

```APIDOC
## GET /api/channels/pending-count

### Description
Get pending message counts.

### Method
GET

### Endpoint
/api/channels/pending-count

```

--------------------------------

### GET /api/agents/:id/compacting/snapshots

Source: https://hivekeep.app/docs/api/rest

Lists compacting summaries in a backwards-compatible legacy format.

```APIDOC
## GET /api/agents/:id/compacting/snapshots

### Description
List compacting summaries (backwards-compatible alias, returns legacy format).

### Method
GET

### Endpoint
/api/agents/:id/compacting/snapshots

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the agent.

### Response
#### Success Response (200)
- **snapshots** (array) - List of compacting summaries in legacy format.

#### Response Example
{
  "snapshots": []
}
```

--------------------------------

### Multi-file app structure

Source: https://hivekeep.app/docs/mini-apps/getting-started

Shows the recommended file structure for a multi-file mini-app, including index.html, app.json, _server.js, styles.css, components/header.jsx, and img/logo.png.

```text
app-files/
├── index.html        # Entry point
├── app.json          # Dependencies
├── _server.js        # Backend (optional)
├── styles.css        # Custom styles
├── components/
│   └── header.jsx    # Additional components
└── img/
    └── logo.png      # Static assets
```

--------------------------------

### GET /api/agents/:id/context-usage

Source: https://hivekeep.app/docs/api/rest

Get context window usage.

```APIDOC
## GET /api/agents/:id/context-usage

### Description
Get context window usage.

### Method
GET

### Endpoint
/api/agents/:id/context-usage

### Parameters
#### Path Parameters
- **id** (string) - Required - Agent ID

### Response
#### Success Response (200)
- **usage** (object) - Context window usage details

#### Response Example
{
  "usage": {}
}
```

--------------------------------

### POST /api/plugins/install

Source: https://hivekeep.app/docs/plugins/api

Installs a plugin from an npm package or a Git URL. The request body must specify the source and either the package name or the Git URL.

```APIDOC
## POST /api/plugins/install

### Description
Installs a plugin from an npm package or a Git URL. The request body must specify the source and either the package name or the Git URL.

### Method
POST

### Endpoint
/api/plugins/install

### Parameters
#### Request Body
- **source** (string) - Required - The source type: "npm" or "git".
- **package** (string) - Required if source is "npm" - The npm package name.
- **url** (string) - Required if source is "git" - The Git URL of the plugin repository.

### Request Example (npm)
```json
{
  "source": "npm",
  "package": "hivekeep-plugin-weather"
}
```

### Request Example (git)
```json
{
  "source": "git",
  "url": "https://github.com/user/hivekeep-plugin-weather"
}
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message.

#### Response Example
```json
{
  "status": "installed"
}
```
```

--------------------------------

### GET /api/channels/:id

Source: https://hivekeep.app/docs/api/rest

Gets details of a specific channel by its ID.

```APIDOC
## GET /api/channels/:id

### Description
Get channel details.

### Method
GET

### Endpoint
/api/channels/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The channel ID.

```

--------------------------------

### GET /api/mini-apps/:id/storage/:key

Source: https://hivekeep.app/docs/api/rest

Gets a value from mini-app storage by key.

```APIDOC
## GET /api/mini-apps/:id/storage/:key

### Description
Get a value.

### Method
GET

### Endpoint
/api/mini-apps/:id/storage/:key

### Parameters
#### Path Parameters
- **id** (string) - Required - The mini-app ID.
- **key** (string) - Required - The storage key.

```

--------------------------------

### File organization structure

Source: https://hivekeep.app/docs/mini-apps/guidelines

Recommended file structure for complex mini-apps, listing entry point, dependencies, backend, styles, and additional components.

```text
index.html          — Entry point + main app component
app.json            — Dependencies
_server.js          — Backend (if needed)
styles.css          — Custom styles (if needed)
components/*.jsx    — Additional React components
```

--------------------------------

### GET /api/mini-apps/by-slug/:agentId/:slug

Source: https://hivekeep.app/docs/api/rest

Gets a mini-app by Agent ID and slug.

```APIDOC
## GET /api/mini-apps/by-slug/:agentId/:slug

### Description
Get mini-app by Agent + slug.

### Method
GET

### Endpoint
/api/mini-apps/by-slug/:agentId/:slug

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The agent ID.
- **slug** (string) - Required - The mini-app slug.

```

--------------------------------

### POST /api/providers/oauth/:type/start

Source: https://hivekeep.app/docs/providers/supported

Begins the CLI-free OAuth sign-in (PKCE) for a subscription provider. Returns the authorize URL.

```APIDOC
## POST /api/providers/oauth/:type/start

### Description
Begins the CLI-free OAuth sign-in (PKCE) for a subscription provider. Returns the authorize URL.

### Method
POST

### Endpoint
/api/providers/oauth/:type/start

### Parameters
#### Path Parameters
- **type** (string) - Required - The provider type for OAuth sign-in.

### Response
#### Success Response (200)
- **authorizeUrl** (string) - The URL to authorize the OAuth flow.

#### Response Example
{
  "authorizeUrl": "https://example.com/authorize"
}
```

--------------------------------

### GET /api/plugins/version

Source: https://hivekeep.app/docs/plugins/api

Gets the Hivekeep version for compatibility checks. This endpoint returns the current Hivekeep version.

```APIDOC
## GET /api/plugins/version

### Description
Get Hivekeep version for compatibility checks.

### Method
GET

### Endpoint
/api/plugins/version

### Response
#### Success Response (200)
- **version** (string) - The Hivekeep version.

#### Response Example
```json
{
  "version": "1.0.0"
}
```
```

--------------------------------

### GET /listeners - Get subscriber count

Source: https://hivekeep.app/docs/mini-apps/backend

Backend endpoint that returns the number of clients currently listening to events.

```APIDOC
## GET /listeners

### Description
Returns the number of clients currently subscribed to the event stream.

### Method
GET

### Endpoint
/listeners

### Parameters
None

### Response
#### Success Response (200)
- **count** (number) - Number of connected clients.

#### Response Example
```json
{
  "count": 0
}
```

```

--------------------------------

### Backend _server.js example

Source: https://hivekeep.app/docs/mini-apps/getting-started

Defines a backend server using Hono. It exports a default function that receives a context with Hono and storage, and sets up a /stats endpoint that returns the total number of keys.

```javascript
export default function(ctx) {
  const app = new ctx.Hono();


  app.get("/stats", async (c) => {
    const keys = await ctx.storage.list();
    return c.json({ totalKeys: keys.length });
  });


  return app;
}
```

--------------------------------

### useApps()

Source: https://hivekeep.app/docs/mini-apps/hooks

List other mini-apps from the same Agent.

```APIDOC
## useApps()

### Description
List other mini-apps from the same Agent.

### Usage
```js
const { apps, loading, refresh } = useApps();
```

### Returns
- **apps** (array) - List of mini-apps.
- **loading** (boolean) - Loading state.
- **refresh** (function) - Refreshes the list.
```

--------------------------------

### Create _server.js with default export

Source: https://hivekeep.app/docs/mini-apps/backend

Create a _server.js file using the write_mini_app_file tool. The file must default-export a function that receives a context object and returns a Hono app (or any object with a .fetch() method). _server.ts is also supported.

```javascript
export default function(ctx) {
  const app = new ctx.Hono();


  app.get("/hello", (c) => {
    return c.json({ message: "Hello from the backend!" });
  });


  return app;
}
```

--------------------------------

### Quick Example: Counter mini-app

Source: https://hivekeep.app/docs/mini-apps/overview

A simple counter mini-app created via the create_mini_app tool. Uses React hooks and components from @hivekeep/react and @hivekeep/components. The app waits for the Hivekeep SDK to be ready before rendering.

```jsx
// Created via create_mini_app tool
<div id="root"></div>
<script type="text/jsx">
import { useState } from "react";
import { createRoot } from "react-dom/client";
import { useHivekeep } from "@hivekeep/react";
import { Card, Button, Stack } from "@hivekeep/components";


function App() {
  const { ready } = useHivekeep();
  if (!ready) return <div>Loading...</div>;
  return <Counter />;
}


function Counter() {
  const [count, setCount] = useState(0);
  return (
    <Card>
      <Card.Header>
        <Card.Title>Counter</Card.Title>
      </Card.Header>
      <Card.Content>
        <Stack direction="row" gap="8px" align="center">
          <Button onClick={() => setCount(c => c - 1)}>-</Button>
          <span style={{ fontSize: '2rem' }}>{count}</span>
          <Button onClick={() => setCount(c => c + 1)}>+</Button>
        </Stack>
      </Card.Content>
    </Card>
  );
}


createRoot(document.getElementById("root")).render(<App />);
</script>
```

--------------------------------

### Prompt to clone repository

Source: https://hivekeep.app/docs/guides/blueprints/github-issue-processor

Tell the Agent to clone the repository into the workspace directory. The Agent will use 'run_shell' to run 'git clone'.

```text
Clone https://github.com/your-org/your-repo.git into your workspace directory.
```

--------------------------------

### useBreakpoint()

Source: https://hivekeep.app/docs/mini-apps/hooks

Current responsive breakpoint.

```APIDOC
## useBreakpoint()

### Description
Current responsive breakpoint.

### Usage
```js
const bp = useBreakpoint();
// "xs" (<640px) | "sm" | "md" | "lg" | "xl" (≥1280px)
```

### Returns
- **breakpoint** (string) - Current breakpoint: "xs", "sm", "md", "lg", or "xl".
```

--------------------------------

### GET /api/vault/entries

Source: https://hivekeep.app/docs/api/rest

List all entries.

```APIDOC
## GET /api/vault/entries

### Description
List all entries.

### Method
GET

### Endpoint
/api/vault/entries

```

--------------------------------

### GET /api/vault

Source: https://hivekeep.app/docs/api/rest

List all vaults.

```APIDOC
## GET /api/vault

### Description
List all vaults.

### Method
GET

### Endpoint
/api/vault

```

--------------------------------

### GET /api/webhooks

Source: https://hivekeep.app/docs/api/rest

Lists all webhooks.

```APIDOC
## GET /api/webhooks

### Description
List webhooks.

### Method
GET

### Endpoint
/api/webhooks

### Response
#### Success Response (200)
- **webhooks** (array) - List of webhooks.

#### Response Example
{
  "webhooks": []
}
```

--------------------------------

### ctx.platform.post example with permissions

Source: https://hivekeep.app/docs/mini-apps/backend

Shows a backend onClientEvent handler that uses ctx.platform.post to create a contact from inbound data. Requires the permission 'platform:contacts:write' in app.json. Writes act with the maintainer Agent's identity.

```json
// app.json: { "permissions": ["platform:contacts:write", "platform:crons:read"] }
```

```javascript
export function onClientEvent(ctx, event, data) {
  // e.g. turn an inbound request into a contact
  return ctx.platform.post("/contacts", { firstName: data.firstName, lastName: data.lastName })
}
```

--------------------------------

### GET /api/contacts

Source: https://hivekeep.app/docs/api/rest

Lists all contacts.

```APIDOC
## GET /api/contacts

### Description
Lists all contacts.

### Method
GET

### Endpoint
/api/contacts

```

--------------------------------

### useShortcut(key, callback)

Source: https://hivekeep.app/docs/mini-apps/hooks

Register keyboard shortcuts. Auto-cleanup on unmount.

```APIDOC
## useShortcut(key, callback)

### Description
Register keyboard shortcuts. Auto-cleanup on unmount.

### Usage
```js
useShortcut("ctrl+k", () => openSearch());
useShortcut("escape", () => close());
```

### Parameters
- **key** (string) - Keyboard shortcut key combination.
- **callback** (function) - Callback to execute when shortcut is pressed.
```

--------------------------------

### GET /api/tasks

Source: https://hivekeep.app/docs/api/rest

Lists all tasks.

```APIDOC
## GET /api/tasks

### Description
Lists all tasks.

### Method
GET

### Endpoint
/api/tasks

### Response
#### Success Response (200)
- **tasks** (array) - List of task objects.
```

--------------------------------

### POST /api/tasks/:id/force-promote

Source: https://hivekeep.app/docs/api/rest

Force-starts a queued task, ignoring the concurrency limit.

```APIDOC
## POST /api/tasks/:id/force-promote

### Description
Force-starts a queued task, ignoring the concurrency limit.

### Method
POST

### Endpoint
/api/tasks/:id/force-promote

### Parameters
#### Path Parameters
- **id** (string) - Required - The task ID.

### Response
#### Success Response (200)
- **status** (string) - Confirmation message.
```

--------------------------------

### GET /api/agents

Source: https://hivekeep.app/docs/api/rest

List all Agents.

```APIDOC
## GET /api/agents

### Description
List all Agents.

### Method
GET

### Endpoint
/api/agents

### Response
#### Success Response (200)
- **agents** (array) - List of Agent objects

#### Response Example
{
  "agents": []
}
```

--------------------------------

### get_user

Source: https://hivekeep.app/docs/agents/tools

Gets user details.

```APIDOC
## get_user

### Description
Gets user details.
```

--------------------------------

### Using card builders for type-safe card layouts

Source: https://hivekeep.app/docs/plugins/migrating-from-01

Shows how to use the new `card.*` builders to get autocomplete and compile-time validation when emitting cards. Hand-written literals still work; the builders are sugar, not gatekeepers.

```typescript
import { card } from '@hivekeep/sdk'


ctx.cards.emit({
  agentId,
  cardType: 'progress',
  layout: [
    { type: 'header', title: 'Working...' },
    { type: 'progress', indeterminate: true },
    card.header({ title: 'Working...' }),
    card.progress({ indeterminate: true }),
  ],
  initialState: {},
})
```

--------------------------------

### Hivekeep.apps.list()

Source: https://hivekeep.app/docs/mini-apps/sdk-reference

Lists all mini-apps from the same Agent.

```APIDOC
## Hivekeep.apps.list()

### Description
Lists all mini-apps from the same Agent.

### Method
SDK Method

### Signature
`await Hivekeep.apps.list()`

### Returns
- **Array** - An array of app objects, each containing `id`, `name`, `slug`, `description`, `icon`, and `version`.

### Example
```js
const apps = await Hivekeep.apps.list();
```
```

--------------------------------

### GET /api/file-storage/:id

Source: https://hivekeep.app/docs/api/rest

Download a file.

```APIDOC
## GET /api/file-storage/:id

### Description
Download a file.

### Method
GET

### Endpoint
/api/file-storage/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The file ID.

```

--------------------------------

### POST /api/mini-apps

Source: https://hivekeep.app/docs/api/rest

Creates a new mini-app.

```APIDOC
## POST /api/mini-apps

### Description
Create a mini-app.

### Method
POST

### Endpoint
/api/mini-apps

```

--------------------------------

### GET /api/file-storage

Source: https://hivekeep.app/docs/api/rest

List stored files.

```APIDOC
## GET /api/file-storage

### Description
List stored files.

### Method
GET

### Endpoint
/api/file-storage

```

--------------------------------

### useApi(path, options?)

Source: https://hivekeep.app/docs/mini-apps/backend

React hook for fetching data from the mini-app backend. It returns data, loading, error, and refetch. The hook accepts an optional second argument with method, body, headers, and enabled options. Pass null as the path to skip fetching.

```APIDOC
## useApi(path, options?)

### Description
React hook for fetching data from the mini-app backend. It returns data, loading, error, and refetch. The hook accepts an optional second argument with method, body, headers, and enabled options. Pass null as the path to skip fetching.

### Parameters
- **path** (string|null) - Required - The API path to fetch. Pass null to skip fetching.
- **options** (object) - Optional - Configuration object.
  - **method** (string) - Optional - HTTP method (e.g., 'GET', 'POST').
  - **body** (object) - Optional - Request body.
  - **headers** (object) - Optional - Request headers.
  - **enabled** (boolean) - Optional - Whether to enable the fetch.

### Returns
- **data** (any) - The response data.
- **loading** (boolean) - Whether the request is in progress.
- **error** (Error|null) - Any error that occurred.
- **refetch** (function) - Function to refetch the data.

### Example
```js
const { data: items, loading, error, refetch } = useApi("/items");
```
```

--------------------------------

### GET /api/vault/types

Source: https://hivekeep.app/docs/api/rest

List vault types.

```APIDOC
## GET /api/vault/types

### Description
List vault types.

### Method
GET

### Endpoint
/api/vault/types

```

--------------------------------

### index.html with JSX script

Source: https://hivekeep.app/docs/mini-apps/getting-started

The entry point for a mini-app. It includes a root div and a JSX script that imports React, createRoot, and useHivekeep. The useHivekeep hook must be called at the root and ready must be true before rendering content.

```html
<div id="root"></div>
<script type="text/jsx">
import { useState } from "react";
import { createRoot } from "react-dom/client";
import { useHivekeep } from "@hivekeep/react";


function App() {
  const { ready } = useHivekeep();
  if (!ready) return <div>Loading...</div>;
  return <h1>Hello, Mini-App!</h1>;
}


createRoot(document.getElementById("root")).render(<App />);
</script>
```

--------------------------------

### GET /api/crons

Source: https://hivekeep.app/docs/api/rest

Lists all cron jobs.

```APIDOC
## GET /api/crons

### Description
List cron jobs.

### Method
GET

### Endpoint
/api/crons

### Response
#### Success Response (200)
- **crons** (array) - List of cron jobs.

#### Response Example
{
  "crons": []
}
```

--------------------------------

### GET /api/providers

Source: https://hivekeep.app/docs/api/rest

Lists all providers with their status.

```APIDOC
## GET /api/providers

### Description
Lists all providers with their status.

### Method
GET

### Endpoint
/api/providers

```

--------------------------------

### ctx.manifest

Source: https://hivekeep.app/docs/plugins/api

Read-only manifest info, just { name, version }.

```APIDOC
## ctx.manifest

### Description
Read-only manifest info, just { name, version }.

### Properties
- **name** (string) - The plugin name.
- **version** (string) - The plugin version.
```

--------------------------------

### Good Task Description Example

Source: https://hivekeep.app/docs/guides/autonomy-quickstart

A self-contained task description for processing a GitHub issue webhook payload. It includes clear context, numbered steps, expected tool calls, and the payload data. Use this as a template for tasks that require the sub-Agent to perform multiple actions and report completion.

```markdown
You are processing a GitHub issue webhook payload.


Your mission:
1. Parse the payload to extract the issue title, body, labels, and author
2. Search the web for any relevant context about the topic
3. Write a triage comment on the issue using the GitHub MCP tools
4. Memorize a summary of your analysis for future reference
5. Call update_task_status("completed", "Triaged issue #<number>: <title>")


The payload:
{{__payload__}}
```

--------------------------------

### ctx.platform.get/post/put/patch/delete(path)

Source: https://hivekeep.app/docs/mini-apps/backend

Manage platform resources from the backend. Requires the `platform:<resource>:<read|write>` permission. No rate limit.

```APIDOC
## ctx.platform.get/post/put/patch/delete(path)

### Description
Manage platform resources from the backend. Requires the `platform:<resource>:<read|write>` permission. No rate limit.

### Method
N/A (SDK methods)

### Endpoint
N/A

### Parameters
- **path** (string) - Required - The resource path.

### Request Example
```js
const data = await ctx.platform.get('/resources/123');
await ctx.platform.post('/resources', { name: 'New' });
```

### Response
#### Success Response
- **data** (object) - The response data from the platform.

#### Response Example
```js
{ "id": "123", "name": "New" }
```

```

--------------------------------

### GET /api/mini-apps/gallery/browse

Source: https://hivekeep.app/docs/api/rest

Browses the mini-app gallery.

```APIDOC
## GET /api/mini-apps/gallery/browse

### Description
Browse mini-app gallery.

### Method
GET

### Endpoint
/api/mini-apps/gallery/browse

```

--------------------------------

### get_agent_details

Source: https://hivekeep.app/docs/agents/tools

Gets full details of an Agent.

```APIDOC
## get_agent_details

### Description
Gets full details of an Agent.
```

--------------------------------

### Multi-Page App with Routing

Source: https://hivekeep.app/docs/mini-apps/examples

Use this snippet to build a settings app with hash-based routing. It includes navigation links and routes for General, Appearance, and Notifications pages. The app uses useHivekeep for readiness and useStorage for persistent settings.

```jsx
<div id="root"></div>
<script type="text/jsx">
import { createRoot } from "react-dom/client";
import { useHivekeep, useStorage } from "@hivekeep/react";
import { Router, Route, NavLink, Card, Stack, Switch, Select, Input } from "@hivekeep/components";


function App() {
  const { ready } = useHivekeep();
  if (!ready) return <div>Loading...</div>;


  return (
    <Router>
      <div className="p-4 space-y-4">
        <Stack direction="row" gap="8px">
          <NavLink to="/" exact>General</NavLink>
          <NavLink to="/appearance">Appearance</NavLink>
          <NavLink to="/notifications">Notifications</NavLink>
        </Stack>
        <Route path="/" element={<GeneralSettings />} />
        <Route path="/appearance" element={<AppearanceSettings />} />
        <Route path="/notifications" element={<NotificationSettings />} />
      </div>
    </Router>
  );
}


function GeneralSettings() {
  const [name, setName] = useStorage("settings.name", "");
  return (
    <Card>
      <Card.Header><Card.Title>General</Card.Title></Card.Header>
      <Card.Content>
        <Input label="Display Name" value={name} onChange={e => setName(e.target.value)} />
      </Card.Content>
    </Card>
  );
}


function AppearanceSettings() {
  const [compact, setCompact] = useStorage("settings.compact", false);
  return (
    <Card>
      <Card.Header><Card.Title>Appearance</Card.Title></Card.Header>
      <Card.Content>
        <Switch label="Compact mode" checked={compact} onChange={setCompact} />
      </Card.Content>
    </Card>
  );
}


function NotificationSettings() {
  return (
    <Card>
      <Card.Header><Card.Title>Notifications</Card.Title></Card.Header>
      <Card.Content><p>Coming soon...</p></Card.Content>
    </Card>
  );
}


createRoot(document.getElementById("root")).render(<App />);
</script>
```

--------------------------------

### LineChart component usage (single and multi-series)

Source: https://hivekeep.app/docs/mini-apps/components

Shows two examples: a single-series line chart with dots and curved lines, and a multi-series chart with an area fill. The multi-series example uses the series prop to label each data series.

```jsx
{/* Single series */}
<LineChart data={[{label: "Mon", value: 10}, {label: "Tue", value: 20}]} showDots curved />
```

```jsx
{/* Multi-series */}
<LineChart data={[{label: "Mon", values: [10, 15]}, {label: "Tue", values: [20, 18]}]} series={["Sales", "Returns"]} showArea />
```