API reference

Derived from the honeycomb knowledge base, captured 2026-06. Route groups, status-code conventions, and the SDK shape are transcribed from the standards and integrations specifications. The knowledge base organizes the API by route group and names the cross-cutting contracts; it does not publish a complete per-endpoint request and response schema for every route. Where exact request or response bodies are not specified, that is noted inline. Confirm precise paths, payloads, and status codes against your installed version (the daemon keeps docs/API.md and the per-group docs accurate to the routes).

honeycomb's data-access API is the HTTP surface of the local honeycomb daemon. The daemon is the only process that talks to the storage backend; every other surface (the CLI, the lifecycle hooks, the MCP server, the SDK) is a thin client that reaches storage through this API. There are two supported ways to consume it: the daemon HTTP API directly, and the typed @honeycomb/sdk client that wraps it.

#The service

The daemon serves everything from one HTTP server, by default on 127.0.0.1:3850. The port, host, and bind address are overridable with HONEYCOMB_PORT, HONEYCOMB_HOST, and HONEYCOMB_BIND (a team deployment widens the bind beyond localhost).

#Route groups

The API is organized into coherent groups. The table maps each group to what it covers and the permission posture it carries in team and hybrid modes (in local mode every route is open).

New routes are expected to land in the right group rather than inventing a parallel namespace.

#Authentication

The API authenticates with a Bearer token or a connector API key, depending on the daemon mode.

#Daemon modes

#Tokens

Login uses the OAuth 2.0 Device Authorization Flow and mints a long-lived, org-bound token, written to ~/.deeplake/credentials.json at mode 0600. The token travels in an HTTP Authorization header, never in a URL query parameter, and only the daemon makes the network call to the storage backend (over TLS).

#Connector API keys

Remote connectors authenticate with named API keys rather than user tokens. Keys are revocable, stored hashed (scrypt with a salt), prefixed hc_sk_..., and printed once at creation. A key carries a role and can be narrowed with an explicit permission list, and can be bound to a connector, harness, agent, and allowed projects. Connector keys default to a narrow permission set (recall, remember, documents).

#Roles

#Cross-cutting contracts

Two contracts cut across every route.

Scoping. Every route that touches user data threads agent_id (or agentId) and threads visibility where the data model supports it, all within the caller's org and workspace tenancy. Org and workspace isolation is enforced at the storage layer, not just at the request layer, so a token minted for one org cannot read another org's data by editing a header. A token or key may additionally carry a tighter scope of project, agent, or user; a request touching a different value for a set field gets 403.

Runtime path. A session uses one active runtime path. Connectors send x-honeycomb-runtime-path: plugin|legacy, and a conflicting path on the same session returns 409. This stops two integration surfaces from writing into one session.

#Errors and status codes

Errors return a structured shape, by default { "error": "human-readable message" }, never a raw stack and never an upstream provider's error verbatim. Status codes carry meaning.

Upstream errors are masked behind client-safe messages. Rate-limited operations surface a dedicated rate-limit error with Retry-After, and dead-lettered jobs are not retried.

#Rate limiting

Rate limiting is enforced only in team and hybrid modes. It is a sliding window keyed by the caller (the token subject or API key; unauthenticated requests share an anonymous bucket) and resets on daemon restart. Expensive and abuse-prone operations (forget, batch operations, admin, inference execution and the gateway, LLM-backed recall) carry tighter limits. Exceeding a limit returns 429 with Retry-After.

#Representative endpoints

The knowledge base names these specific endpoints with enough detail to call out here. For the full request and response bodies of each, consult the daemon's own docs/API.md and per-group docs on your installed version.

There is deliberately no GET /api/secrets/:name: a secret value can never be read through the API.

#The SDK

@honeycomb/sdk is a typed HTTP client with no native dependencies, safe in Node, Bun, and the browser. It wraps the daemon API so an application gets memory without speaking raw HTTP.

import { HoneycombClient } from "@honeycomb/sdk";

const honeycomb = new HoneycombClient({
  daemonUrl: "http://localhost:3850",
  token: "Bearer hc_sk_...",   // for team / hybrid daemon modes
  actor: "agent-name",
  actorType: "llm",
});

await honeycomb.remember("prefers TypeScript", { importance: 0.9, tags: "language" });
const { results } = await honeycomb.recall("language preferences", { limit: 5 });

The client covers memory, the hook entry points, connectors and documents, sources, skills and goals, health and diagnostics, and the value-safe secrets surface. React bindings, a Vercel AI SDK helper, and an OpenAI tool helper ship alongside the core client.

#Retry and error semantics

• GET requests retry; mutating requests do not, because mutations are not idempotent.
• Errors are typed: an API error for non-2xx responses, a network error for transport failures, and a timeout error when a request exceeds the configured budget.
• Authenticated calls carry the same token and API-key model as the rest of the daemon.

The package name @honeycomb/sdk, the constructor options, and the remember / recall method shapes are transcribed from the knowledge base. The full method list is described by capability area rather than enumerated method by method; confirm exact method names and signatures against your installed SDK version's types.

#Choosing a consumption surface

All four end at the same daemon API, so the choice is about the calling environment, not about capability.

#Related

• CLI reference
• MCP tools reference
• Architecture overview
• Security model
• Data and storage spec