SDK Reference

The Hivekeep SDK (hivekeep-sdk.js) is the low-level API that powers the React hooks. You can use it directly for non-React apps or advanced use cases.

Hivekeep Global Object

After the SDK loads, the Hivekeep global is available.

Lifecycle

Hivekeep.ready()  // Signal that the app has finished loading

Note

ready() is a method you call once your app is initialized, not a boolean property. The parent waits for this signal before showing the app.

App Info

Hivekeep.app
// { id, name, slug, agentId, agentName, agentAvatarUrl, isFullPage, locale, user }

Hivekeep.agent       // { id, name, avatarUrl }
Hivekeep.user      // { id, name, pseudonym, locale, timezone, avatarUrl }
Hivekeep.locale    // string — current UI language code (e.g. 'en', 'fr')
Hivekeep.version   // string — SDK version
Hivekeep.isFullPage // boolean — whether the app is in full-page mode

Theme

Hivekeep.theme       // { mode: "light"|"dark", palette: string }
Hivekeep.on("theme-changed", ({ mode, palette }) => { ... })

Events

Listen for parent events or emit your own:

Hivekeep.on(eventName, callback)   // Listen for events from the parent
Hivekeep.emit(eventName, data?)    // Send events to the parent

Built-in event names:

Event	Description
theme-changed	Theme mode or palette changed
app-meta	App metadata updated
locale-changed	UI language changed
fullpage-changed	Full-page mode toggled
shared-data	Data received from another mini-app

Storage

Persistent key-value storage (server-side, max 64KB per value, 500 keys per app).

await Hivekeep.storage.get(key)      // → value | null
await Hivekeep.storage.set(key, value)  // JSON-serializable
await Hivekeep.storage.delete(key)   // → boolean (true if deleted)
await Hivekeep.storage.list()        // → [{ key, size }]
await Hivekeep.storage.clear()       // → number (keys cleared)

Note

list() takes no arguments and returns objects with key and size (bytes), not just key strings.

Navigation & Display

Hivekeep.navigate(path)          // Navigate the parent Hivekeep UI to a path
Hivekeep.fullpage(bool)          // Toggle full-page or side-panel mode
Hivekeep.setTitle(title)         // Dynamically update the panel header title
Hivekeep.setBadge(value)         // Set sidebar badge (number, string, or null to clear)
Hivekeep.resize(width?, height?) // Request panel resize (320-1200px width, 200-2000px height)
Hivekeep.openApp(slug)           // Open another mini-app from the same Agent by slug

Messaging

await Hivekeep.sendMessage(text, options?)
// Send a message to the Agent's conversation
// options: { silent?: boolean }
// Rate limited: 5 per 30s

await Hivekeep.conversation.history(limit?)
// Get recent messages (default 20, max 100)
// Returns: [{ id, role, content, createdAt, sourceType }]

await Hivekeep.conversation.send(text, options?)
// Alias of sendMessage

Memory

await Hivekeep.memory.search(query, limit?)
// Semantic search Agent memories (default 20, max 50)
// Returns: [{ id, content, category, subject, score, updatedAt }]

await Hivekeep.memory.store(content, { category?, subject? })
// Store a new memory
// category: "fact" | "preference" | "decision" | "knowledge" (default)
// Max 2000 chars
// Returns: { id, content, category, subject }

Clipboard

await Hivekeep.clipboard.write(text)  // Copy text to system clipboard (bypasses iframe restrictions)
await Hivekeep.clipboard.read()       // Read text from system clipboard (may require permission)

Notifications

await Hivekeep.notification(title, body?)  // → boolean
// Shows a browser notification via the parent window

Toast & Dialogs

These are methods on the Hivekeep object directly:

Hivekeep.toast("Saved!", "success")
// type: "info" (default) | "success" | "warning" | "error"

const ok = await Hivekeep.confirm("Delete this item?", {
  title: "Confirm",
  confirmText: "Delete",
  cancelText: "Cancel",
})
// Returns: boolean

const name = await Hivekeep.prompt("Enter your name", {
  title: "Input",
  placeholder: "John Doe",
  defaultValue: "",
  confirmText: "OK",
  cancelText: "Cancel",
})
// Returns: string | null

Note

In the React layer (@hivekeep/react), toast, confirm, and prompt are re-exported as standalone functions for convenience. Under the hood they call these same SDK methods.

Keyboard Shortcuts

const unregister = Hivekeep.shortcut("ctrl+k", callback)
// Returns unregister function. Pass null callback to remove.
// Examples: "ctrl+k", "meta+shift+p", "escape"

File Downloads

await Hivekeep.download(filename, content, mimeType?)
// content: string, object (auto-JSON), Blob, or ArrayBuffer
// mimeType is auto-detected if omitted

Inter-App Communication

Hivekeep.share(targetSlug, data)
// Share JSON data with another mini-app and open it
// Note: this is synchronous (fire-and-forget)

Hivekeep.on("shared-data", ({ from, fromName, data, ts }) => { ... })
// Receive shared data from another app

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 }

HTTP Proxy

Make external HTTP requests via Hivekeep’s server (bypasses CORS). Rate limited: 60 req/min, 5MB max, 15s timeout.

const res = await Hivekeep.http(url, options?)
const data = await Hivekeep.http.json(url)
const data = await Hivekeep.http.post(url, body)

Backend API Client

Call routes defined in _server.js:

const data = await Hivekeep.api.get("/path")         // GET → JSON
const data = await Hivekeep.api.post("/path", body)   // POST → JSON
const data = await Hivekeep.api.put("/path", body)     // PUT → JSON
const data = await Hivekeep.api.patch("/path", body)   // PATCH → JSON
const data = await Hivekeep.api.delete("/path")        // DELETE → JSON
const data = await Hivekeep.api.json("/path", headers?) // GET + JSON parse
const res = await Hivekeep.api("/path", opts?)          // Raw Response

Server-Sent Events

Subscribe to real-time events from the backend (_server.js using ctx.events.emit()).

Hivekeep.events.on("eventName", (data) => { ... })
Hivekeep.events.subscribe((event) => { ... })  // all events — { event, data }
Hivekeep.events.close()
Hivekeep.events.connected  // boolean

CSS Design System

A design system CSS is auto-injected into every mini-app.

CSS Variables

/* Core */
var(--color-primary)
var(--color-background)
var(--color-foreground)
var(--color-muted)
var(--color-card)
var(--color-border)

/* Semantic */
var(--color-secondary)
var(--color-accent)
var(--color-destructive)
var(--color-success)
var(--color-warning)
var(--color-info)

/* Charts */
var(--color-chart-1) through var(--color-chart-5)

/* Gradients & effects */
var(--color-gradient-start)
var(--color-gradient-mid)
var(--color-gradient-end)
var(--color-glow-1) through var(--color-glow-3)
var(--color-glass-bg)
var(--color-glass-strong-bg)

/* Typography */
var(--font-sans)
var(--font-mono)

/* Radius */
var(--radius-sm) through var(--radius-full)

/* Shadows */
var(--shadow-xs) through var(--shadow-xl)

Utility Classes

Layout (Tailwind-like): .flex, .flex-col, .grid, .grid-cols-2, .items-center, .justify-between, .gap-4, .p-4, .m-4, .w-full, .max-w-md, .space-y-4, .overflow-auto.

Typography: .text-sm, .text-xl, .font-bold, .text-center.

Appearance: .bg-card, .bg-muted, .border, .rounded-lg, .shadow-md.

Components: .btn, .btn-primary, .card, .input, .badge, .table, .spinner.

Glass/Effects: .glass-strong, .surface-card, .gradient-primary, .btn-shine, .card-hover.

Responsive Utilities

Breakpoints: sm (≥640px), md (≥768px), lg (≥1024px), xl (≥1280px).

Prefix any utility: md:grid-cols-2, lg:hidden, sm:flex-row.

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

Animations

.animate-fade-in, .animate-fade-in-up, .animate-slide-in-left, .animate-scale-in, .animate-bounce-in, .animate-shake, .animate-spin, .animate-wiggle, .animate-levitate.

Modifiers: .delay-1 to .delay-10, .duration-75 / .duration-1000.

Transitions: .transition-all, .transition-colors, .ease-bounce, .ease-spring.

All animations respect prefers-reduced-motion.

TypeScript Definitions

Full type definitions are available at:

• /api/mini-apps/sdk/hivekeep-sdk.d.ts
• /api/mini-apps/sdk/hivekeep-react.d.ts
• /api/mini-apps/sdk/hivekeep-components.d.ts