Search & Recall

Ask gives you answers. This page gives you the raw retrieval surface underneath it — the endpoints you call when you want ranked evidence, structured records, or a full extract to feed your own systems: sync pipelines, audit tooling, agent context windows, or a search box in your own product.

Every endpoint here uses your API key (Authorization: Bearer hck_...) and returns only what the caller is allowed to see — records are isolated to your organization and scoped by Spaces. When you call on behalf of a specific person, add the x-acting-user header and results narrow to that person's view.

At a glance

• POST /api/v1/search — ranked, reranked retrieval over everything your organization has ingested. Five modes; hybrid is the default and the right choice most of the time.
• GET /api/v1/memories — browse or filter distilled memories directly, as structured records rather than ranked hits.
• Time travel — GET /memories/delta tells you what changed since a timestamp (perfect for sync); POST /memories/at reconstructs what was known at a past moment (perfect for audits).
• The directory — /entities/:name, /people/:name, /experts, /company, /org-chart, and /who-should-handle turn your corpus into a queryable map of who knows what.
• GET /api/v1/export — a portable, integrity-verifiable extract of your whole memory store. It's your data.
• Agents get the same power via the MCP tools honeycomb_search, honeycomb_recall, and honeycomb_context — see Agents & MCP.

Choosing the right endpoint

Search: POST /api/v1/search

Search runs a staged retrieval pipeline: it scopes to what you're allowed to see, retrieves candidates by meaning and by keyword, then reranks the pool for answer-bearing relevance — not just topical overlap. Facts that several independent sources corroborate are ranked more strongly, so well-established truths surface above one-off mentions. You get back a ranked list of results, each carrying its content, provenance, and the entities it mentions.

curl -s "$HONEYCOMB_URL/api/v1/search" \
  -H "Authorization: Bearer hck_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Meridian renewal terms",
    "mode": "hybrid",
    "limit": 5,
    "scope": {
      "namespace": "sales",
      "source": "hubspot",
      "dateRange": { "from": "2026-01-01" }
    }
  }'

{
  "results": [
    {
      "id": "pt_9",
      "knowledgeEntryId": "ke_3",
      "score": 0.82,
      "content": "Meridian renewed for $240k ARR on Jan 4...",
      "title": "Meridian renewal",
      "namespace": "sales",
      "contentType": "deal_note",
      "sourceAgent": "crm-sync",
      "tags": ["renewal"],
      "validFrom": "2026-01-04",
      "source": "hubspot",
      "entities": [{ "name": "Meridian", "type": "customer" }],
      "memory": { "memoryId": "m_7", "memoryType": "milestone", "documentDate": "2026-01-04" }
    }
  ],
  "totalFound": 1,
  "query": "Meridian renewal terms",
  "mode": "hybrid",
  "searchTimeMs": 143
}

Modes

Request options

Scope filters

All filters combine with AND. String filters accept a single value or an array.

Note: spaceId and threadId can only narrow what you see. They never grant access beyond the caller's Spaces, and results are double-checked against Space membership before they're returned.

Browsing memories

Search gives you ranked hits. The memory endpoints give you the records themselves — distilled, deduplicated units of knowledge with their entity links and validity windows. Reach for these when you're building a sync job, rendering a feed, or assembling agent context and you want structure, not ranking.

GET /api/v1/memories

With a query parameter, this ranks memories by relevance. Without one, it's a straight filtered listing, newest first.

curl -s "$HONEYCOMB_URL/api/v1/memories?namespace=support&memoryType=commitment&limit=20" \
  -H "Authorization: Bearer hck_..."

Response: { "results": [...], "totalFound": 12 }.

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

Every current memory linked to one entity — the fastest way to load "everything we know about this account" into an agent's context. Accepts optional query (relevance ranking) and limit params.

GET /api/v1/memories/:id

One memory by id, including its entity links and its relations to other memories.

Note: a memory you don't have access to returns 404, not 403 — the API never confirms the existence of records outside your view.

Time travel

Honeycomb keeps validity windows on every memory, which unlocks two questions ordinary search can't answer.

What changed? — GET /api/v1/memories/delta

Pass a timestamp and get everything added, expired, or updated since. This is the backbone of an incremental sync: store the timestamp of your last run, poll the delta, apply the changes to your own store.

curl -s "$HONEYCOMB_URL/api/v1/memories/delta?since=2026-07-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer hck_..."

{
  "added":   [{ "id": "m_91", "content": "Meridian expanded to 3 new regions...", "documentDate": "2026-07-03" }],
  "expired": [{ "id": "m_12", "content": "Meridian contract under negotiation...", "expiredAt": "2026-07-02" }],
  "updated": []
}

since is required and must be ISO 8601 — anything else returns 400. Optional entityId and namespace narrow the window.

What did we know then? — POST /api/v1/memories/at

Reconstruct the state of knowledge at any past instant: every memory that was valid at that moment, including ones that have since been superseded. Use it for audits ("what did we know when we approved this?"), postmortems, and reproducing an agent's context at decision time.

curl -s "$HONEYCOMB_URL/api/v1/memories/at" \
  -H "Authorization: Bearer hck_..." \
  -H "Content-Type: application/json" \
  -d '{ "timestamp": "2026-03-15T12:00:00Z", "entityId": "e_meridian", "limit": 50 }'

Response: { "results": [...], "totalFound": 8, "asOf": "2026-03-15T12:00:00Z" }.

The directory: entities and people

Your memory store doubles as a living directory of accounts, projects, and people — assembled from evidence, not from a stale wiki page.

GET /api/v1/entities/:name — full recall

The deepest single lookup: current facts, memories, relationships, and (at full depth) a timeline and recent mentions for any entity. Fuzzy name matching is built in.

curl -s "$HONEYCOMB_URL/api/v1/entities/Meridian?depth=full" \
  -H "Authorization: Bearer hck_..."

Response fields: entity, currentFacts, memories, relationships, plus timeline, observationLog, and recentMentions at full depth. An unknown entity returns 404.

People and org lookups

curl -s "$HONEYCOMB_URL/api/v1/experts?topic=billing&limit=3" \
  -H "Authorization: Bearer hck_..."

{
  "topic": "billing",
  "experts": [
    { "name": "Wei Chen", "entityId": "e_5", "score": 12, "signals": ["owns", "works_on"], "evidenceEntryIds": ["ke_1", "ke_2"] }
  ]
}

These endpoints power routing bots, on-call escalation, and "warm intro" features — and they stay current because they're recomputed from what your organization actually does.

Full extracts: GET /api/v1/export

Your organization's memory is yours. The export endpoint produces a portable bundle of your store with SHA-256 receipts so you can verify integrity independently.

# Manifest only (the receipts)
curl -s "$HONEYCOMB_URL/api/v1/export" -H "Authorization: Bearer hck_..."

# The complete bundle
curl -s "$HONEYCOMB_URL/api/v1/export?full=true" -H "Authorization: Bearer hck_..." -o export.json

Note: for ongoing replication, prefer polling /memories/delta — export is built for full extracts, backups, and portability, not incremental sync.

Access and scoping, in one paragraph

Every endpoint on this page respects the same rules: your API key binds requests to your organization, and reads are filtered to org-public content plus the Spaces the acting user has been granted. Adding x-acting-user: [email protected] narrows results to Jane's view — essential when a shared backend serves many users. Scoping happens server-side on every request; there is no client-side flag that widens visibility. Details in Spaces & Permissions.

Where to next

• Ask — when you want an answer with citations instead of raw evidence.
• Agents & MCP — the same retrieval surface as MCP tools: honeycomb_search, honeycomb_recall, honeycomb_context, honeycomb_ingest, honeycomb_upload, honeycomb_manage.
• API Reference — every endpoint, parameter by parameter.
• Ingesting Data — how content becomes the memories you're retrieving here.