API Reference

This is the complete reference for Honeycomb's REST API — the same surface the web console and the MCP tools are built on. Everything here works with just your API key. For narrative guides, each section links to the page that covers it in depth.

At a glance

• Base URL: your workspace's endpoint, shown in the console. Examples use $HONEYCOMB_URL.
• Auth: Authorization: Bearer hck_... on every request. Keys are minted per workspace — treat them like passwords.
• Format: JSON in, JSON out. Send Content-Type: application/json on every request with a body.
• Scoping is automatic: every record is isolated to your organization and scoped by Spaces — the API never returns data the caller isn't allowed to see.
• Acting on behalf of users: send x-acting-user with a user's email to scope reads and shares to that person (requires a key provisioned for it).
• Rate limits: exceeding them returns 429 with a Retry-After header — back off and retry.

Authentication

Every endpoint (except GET /api/v1/health) requires your workspace API key as a Bearer token: Authorization: Bearer hck_live_4f8a2c91d0b7. Keys are minted per workspace and shown once at creation — store them in a secret manager, never in client-side code or version control. If a key leaks, revoke it from the console Admin screen and mint a new one. See Security for key-handling guidance.

When your application serves many people, add the x-acting-user header so Honeycomb scopes the request to that person's visibility:

curl "$HONEYCOMB_URL/api/v1/digest" \
  -H "Authorization: Bearer hck_live_4f8a2c91d0b7" \
  -H "x-acting-user: [email protected]"

Note: Only keys provisioned with acting-user capability may impersonate. Sharing endpoints and the personal digest require an acting user — without one they return 403 or an empty result.

Every request flows through the same pipeline before your handler runs:

Errors

Errors return JSON with an error message; validation failures add a details array pinpointing each bad field.

Rate limits

When you exceed your workspace's rate limit, the API responds 429 with a Retry-After header (seconds) and a JSON body:

{ "error": "Too Many Requests", "retryAfterSeconds": 42 }

Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can pace clients proactively. For bulk work, prefer POST /api/v1/ingest/batch with modest concurrency over parallel single ingests.

Endpoint index

Ingest

Full guide: Ingesting data.

POST /api/v1/ingest

Body: content (string or array of strings, max 1 MB each) plus metadata — namespace, contentType, and sourceAgent are required; source, sourceChannel, title, tags, externalRef, validFrom, validUntil, audience, and orgWide are optional. An options object tunes processing: extractionTier (0 fastest to 2 deepest, default 1), deferReflection for bulk loads, and onConflict (skip or supersede) for records re-sent with changed content under the same externalRef. Returns 201:

{ "id": "ke_8f2a1c", "chunksCreated": 3, "entitiesExtracted": 5, "factsRecorded": 2, "memoriesExtracted": 4, "extractionTier": 1, "deduplicated": false }

POST /api/v1/ingest/batch

Body: items (1-100 ingest bodies) and optional concurrency (1-20, default 5). Returns 201 when every item succeeds, 207 when any fail — each result carries its index and either a result or an error string, so one bad item never sinks the batch:

{ "total": 3, "succeeded": 2, "failed": 1, "results": [{ "index": 0, "success": true, "result": { "id": "ke_1" } }, { "index": 1, "success": false, "error": "content too long" }], "durationMs": 812 }

POST /api/v1/upload

Multipart form upload — the file field must be named file (PDF, DOCX, TXT, CSV, MD, or JSON, max 10 MB). Required fields: namespace, contentType, sourceAgent; optional: title, source, sourceChannel, tags (comma-separated), extractionTier. Returns 201 with the standard ingest result plus filename and textLength.

POST /api/v1/webhook/:source

Point any tool's outbound webhook here — :source is a freeform label like crm or statuspage. Recognized payload formats are parsed structurally; anything else is ingested best-effort from its text fields. Returns 201. See Connectors for source-specific setup.

POST /api/v1/entries/tombstone

Permanently deletes a record's entire version history plus every memory, fact, and graph edge derived from it. Body: { "externalRef": "zendesk:ticket:4312" }. Returns 200 with deletion counts (entriesDeleted, memoriesDeleted, factsDeleted, edgesDeleted). Returns 404 if memory lifecycle isn't enabled for your workspace.

Warning: Tombstone is irreversible. It exists for right-to-be-forgotten and disconnect flows — not routine cleanup.

Ask & Search

Full guides: Ask and Search and recall.

POST /api/v1/ask

Body: query (required), plus optional scope filters (namespace, contentType, source, sourceChannel, tags, dateRange, spaceId, threadId), effort (low, medium, high), and asOf for point-in-time answers. Add ?trace=1 to include a retrieval trace. Returns 200:

{ "answer": "Meridian Health renewed at $2.4M ARR on January 4 [1].", "answered": true, "confidence": 0.86, "citedIndices": [1], "results": [{ "id": "pt_9", "content": "Meridian Health renewed at $2.4M ARR..." }], "mode": "hybrid", "searchTimeMs": 143 }

When the evidence isn't in memory, answered is false and the answer says what's missing instead of guessing.

POST /api/v1/search

Body: query (required), mode (semantic, keyword, hybrid — default, graph, temporal), limit (1-200, default 10), exhaustive (widen the net for counting questions), scoreThreshold, rerank, and the same scope filters as /ask. Returns 200 with results (each carrying id, score, content, title, namespace, contentType, source, tags), totalFound, and searchTimeMs.

POST /api/v1/context

Assembles a briefing for an agent about to start a task. Body: task (required, e.g. customer_interaction), optional entities array, namespace, and maxTokens. Returns 200 with entitySummaries, relevantPolicies, recentInteractions, and activeFlags.

GET /api/v1/suggestions

Four ready-to-ask questions generated from what's actually in your memory — real people, real projects, real open threads — for suggestion chips in a UI. Query param: kind = ask (default) or timeline. Returns 200:

{ "suggestions": ["What did Priya decide about the Meridian renewal?", "…", "…", "…"], "cached": false }

Suggestions are scoped to the acting user's visibility and cached for ten minutes per user. On a brand-new store you get a sensible starter set instead of an error.

GET /api/v1/threads/:threadId/digest

The rolling distilled summary of one conversation thread — what the thread is about and where it stands, kept current as the conversation evolves. Returns 200 with { "digest": { "content", "title", "updatedAt", "sourceChannel" } }, or { "digest": null } when the thread has no digest yet. Visibility follows the thread's Space — if you can't read the thread, the digest reads as absent. Asking a question scoped to the thread uses this same digest as the backbone of the answer.

Memories & Time Travel

GET /api/v1/memories

Query params: query (semantic search when present, otherwise a filtered list), namespace, entityId, memoryType, currentOnly (default true — set false to include superseded memories), limit (max 200), dateRange.from and dateRange.to. Returns { "results": [], "totalFound": 0 }.

GET /api/v1/memories/delta

What changed since a moment — ideal for agents syncing state. Query params: since (ISO timestamp, required), entityId, namespace, limit. Returns the new, updated, and superseded memories since that time.

POST /api/v1/memories/at

Time travel: what did we know then? Body: timestamp (ISO, required), optional entityId, namespace, limit. Returns { "results": [], "totalFound": 0, "asOf": "2026-03-01T00:00:00Z" }.

GET /api/v1/memories/entity/:entityId

All current memories linked to an entity, newest first. Add ?query= to rank by relevance instead. Returns { "results": [], "totalFound": 0 }.

GET /api/v1/memories/:id

One memory with its entity links and related memories. Returns 404 if it doesn't exist or isn't visible to you.

PATCH /api/v1/memories/:id/promote

Consent-gated widening of who may see a memory. Body: { "scope": "team" } or { "scope": "org" }. Scope only widens — narrowing returns 409. Returns { "ok": true, "consentScope": "team" }.

Entities & People

GET /api/v1/entities/:name

Everything known about an entity. Query params: depth (summary default, full, relationships), includeFacts, includeRelationships, includeMentions, query (rank memories by relevance), memoryLimit. Returns the entity, its current facts, timeline, relationships, and memories — filtered to your visibility. URL-encode names with spaces.

GET /api/v1/graph

Your knowledge graph, scoped to what the caller may see. Query params: limit (max 5000), includeExpired, spaceId, threadId. Returns nodes (entities with mention counts), edges (typed relationships with confidence, attestations, and status — active, reassessed, or invalidated), and stats.

GET /api/v1/experts

?topic=billing (required, plus optional limit) returns ranked experts — each with name, entityId, score, the signals behind the ranking (like owns or works_on), and evidenceEntryIds you can trace back to source.

GET /api/v1/people/:name

A person's working profile: owns, reportsTo, manages, expertise, recentActivity. Returns 404 if the person isn't known yet.

GET /api/v1/company

Your organization's own briefing — org, founders, leadership, keyPeople — inferred from memory.

GET /api/v1/org-chart

Reporting lines inferred from memory: { "nodes": ["Wei Chen"], "edges": [{ "manager": "Dana Ortiz", "report": "Wei Chen", "via": "reports_to" }] }.

POST /api/v1/who-should-handle

Body: { "question": "Customer asking about SSO pricing" }. Returns the resolved topic and the same expert ranking as /experts.

GET and PUT /api/v1/org-profile

Read or replace the editable vocabulary — your industry's canonical entities, relationship types, and domains — that steers how Honeycomb extracts structure from your content. PUT takes { "profile": { ... } } and returns the saved profile. Also editable on the console Admin screen.

Spaces & Sharing

Sharing acts as a person, so these endpoints require the x-acting-user header. Only a Space's owner can share or revoke it (you can always revoke your own access). Full model: Spaces and permissions.

POST /api/v1/spaces/:id/shares

Body: principalId or email (one required), optional role (reader default, or owner). Returns 204. Returns 403 if you're not the Space's owner.

DELETE /api/v1/spaces/:id/shares/:principalId

Revokes a grant. Owners can revoke anyone; anyone can revoke themselves to leave a shared Space. Returns 204.

POST /api/v1/entries/:id/share

Shortcut: share the Space a specific document lives in. Body: principalId or email. Returns { "shared": true, "spaceId": "...", "principalId": "..." }; 404 if the document has no Space, 403 if you don't own it.

GET /api/v1/spaces/shared-with-me and shared-by-me

Two mirrored lists for the acting user: Spaces others granted to you (each with spaceId, kind, label, role, sharedBy, sharedAt), and grants you've created for others (with recipient and role).

Insights & Digest

Full guide: Insights.

GET /api/v1/insights

Query params: status, type, limit, and evidence=true to attach the source memories behind each insight. Each insight carries a type (e.g. automation_opportunity, contradiction), title, body, score, the people involved, and evidence references.

PATCH /api/v1/insights/:id

Triage. Body: { "status": "acknowledged" } or { "status": "dismissed", "reason": "already automated" } — the reason teaches the miner what not to resurface. Returns { "ok": true }.

GET /api/v1/digest

"What do I need to know?" — scoped to the acting user's visibility. Query param: limit. Returns { "digest": [] }.

POST /api/v1/insights/mine

Kick off a mining pass now instead of waiting for the background schedule. Body: optional { "namespace": "support" }. Returns the fresh insights.

GET /api/v1/insights/status

Diagnostics for an empty feed: whether mining is enabled, insight counts by type, and lastInsightAt.

POST /api/v1/insights/:id/agent-prompt

Turns a mined automation opportunity into a paste-ready agent specification, grounded in that insight's own evidence. Returns { "prompt": "..." }.

GET /api/v1/agents/recommended

The opportunity feed shaped for a build-an-agent UI. Query params: limit (max 100), signalType (recurring_toil, sla_gap, periodic, pain_bottleneck). Each entry has name, signalType, rationale, score, evidenceCount, and people.

Export & Health

GET /api/v1/export

Your memory as a portable bundle with SHA-256 receipts for integrity verification. Default returns the manifest only; ?full=true streams the complete bundle. Your data is yours — see Security.

GET /api/v1/health

Unauthenticated health check. Returns 200 with component statuses when healthy, 503 otherwise.

GET /api/v1/sources/health

Is the firehose alive? Per-source ingest counts, lastSeen, and enrichment backlog:

{ "sources": [{ "source": "slack", "count": 1200, "lastSeen": "2026-07-07T09:00:00Z", "backlog": 20 }], "totalBacklog": 20 }

Prefer MCP for agents

If you're wiring an AI agent rather than an application, skip raw REST — the MCP server exposes the same capabilities as six tools: honeycomb_search, honeycomb_ingest, honeycomb_recall, honeycomb_manage, honeycomb_context, and honeycomb_upload, all with the same permission scoping. See Agents and MCP.