Quickstart

Honeycomb is your organization's memory: you feed it the messages, meeting notes, tickets, and documents your company produces, and it gives you back grounded answers with citations. This page takes you from zero to your first cited answer in about ten minutes, using nothing but the web console and curl.

At a glance

• Sign in to the console with your work email and pick your organization's memory store.
• Create an API key — it starts with hck_, it's shown exactly once, and it authenticates every request.
• Ingest content with POST /api/v1/ingest — you get a 201 immediately; enrichment runs in the background.
• Watch it land on the console's Sources page, where every document and its extracted knowledge is visible.
• Ask a question with POST /api/v1/ask — the answer comes back with inline [n] citations pointing at your source.

Here's the loop you're about to run:

Before you begin

You'll need:

1. Console access — an invitation to your organization's Honeycomb console. If you don't have one, ask your workspace admin.
2. Your API base URL — provided when your organization's workspace is set up. The examples below use a HONEYCOMB_URL environment variable.
3. A terminal with curl — or any HTTP client you prefer.

Step 1 — Sign in and find your memory store

Open the console and sign in with your work email (a 6-digit code is emailed to you) or with Google.

After sign-in you land in your organization's workspace. Every organization has at least one memory store — the isolated container that holds all of its ingested knowledge. If you belong to multiple organizations, the switcher in the sidebar lets you change the active one. Everything you do in the console, and every API key you create, is scoped to the active store.

Note: Each memory store is fully isolated. Nothing you ingest is ever visible to another organization, and within your organization, access is further scoped by Spaces — see Spaces and permissions.

Step 2 — Create an API key

1. In the console, open Admin and select the API keys tab.
2. Give the key a name you'll recognize later (for example, Quickstart), and create it.
3. Copy the key immediately. It starts with hck_, and it is shown exactly once — it cannot be retrieved again. If you lose it, revoke it and create a new one.

The key is bound to your memory store server-side, so there's nothing else to configure — no tenant IDs, no extra headers. You present it as a standard bearer token:

export HONEYCOMB_URL="https://your-honeycomb-endpoint"
export HONEYCOMB_API_KEY="hck_..."

Warning: Treat the key like a password. Anyone holding it can read and write your store's memory. Keep it in a secrets manager, never in client-side code or a git repository.

Step 3 — Ingest your first content

Let's ingest something realistic: a message from a public sales channel announcing a renewal. Run this:

curl -s -X POST "$HONEYCOMB_URL/api/v1/ingest" \
  -H "Authorization: Bearer $HONEYCOMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Priya Sharma: Heads up team — Meridian Health signed the renewal this morning. $240k ARR, 24-month term. Kickoff call with their CTO Dan Wallace is next Thursday.",
    "metadata": {
      "namespace": "sales",
      "contentType": "message",
      "sourceAgent": "quickstart-demo",
      "source": "slack",
      "sourceChannel": "#sales",
      "sourceChannelPublic": true,
      "title": "Meridian Health renewal announcement",
      "tags": ["renewal", "meridian-health"]
    }
  }'

The three required metadata fields, plus the optional ones this example uses:

Note: Honeycomb fails closed on visibility. Content with ambiguous provenance is routed to a private Space rather than shared org-wide — that's why this example sets sourceChannelPublic: true for a public channel. The full routing rules live in Ingesting data and Spaces and permissions.

You'll get a 201 back in well under a second:

{
  "id": "ke_a1b2c3",
  "chunksCreated": 1,
  "entitiesExtracted": 3,
  "factsRecorded": 1,
  "memoriesExtracted": 2,
  "extractionTier": 1,
  "deduplicated": false,
  "backgroundProcessing": {
    "queued": true,
    "pendingTasks": 1,
    "rejectedTasks": 0,
    "failures": 0
  }
}

Reading the response:

• id — the document's identifier in your store.
• entitiesExtracted — Honeycomb already spotted the people and companies in the message: Priya Sharma, Meridian Health, Dan Wallace.
• backgroundProcessing.queued: true — enrichment is asynchronous. The fast extraction pass runs inline, then deeper enrichment (facts, atomic memories, graph relationships) continues in the background. Everything is typically queryable within a minute.

Step 4 — Watch it land in the console

Switch back to the console:

1. Open Sources and select the Documents tab. Your document is there, with its enrichment status. Click it to open the provenance view — every entity, fact, and memory derived from it, each traceable back to this exact source.
2. Open Timeline and search for Meridian Health. Once enrichment completes, the renewal shows up as an event on the topic's timeline.

The Sources page is your ground truth while you build an integration: if a document appears there, it made it in; its enrichment status tells you whether the extracted knowledge is ready to answer questions. See Console for a tour of every screen.

Step 5 — Ask your first question

Now the payoff. Ask a question against your memory:

curl -s -X POST "$HONEYCOMB_URL/api/v1/ask" \
  -H "Authorization: Bearer $HONEYCOMB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the terms of the Meridian Health renewal?"
  }'

The response is an answer with receipts:

{
  "answer": "Meridian Health signed a renewal at $240k ARR on a 24-month term, announced by Priya Sharma; a kickoff call with their CTO Dan Wallace is scheduled for next Thursday [1].",
  "answered": true,
  "confidence": 0.87,
  "citedIndices": [1],
  "results": [
    {
      "id": "pt_9f2k",
      "knowledgeEntryId": "ke_a1b2c3",
      "score": 0.82,
      "content": "Priya Sharma: Heads up team — Meridian Health signed the renewal this morning...",
      "title": "Meridian Health renewal announcement",
      "namespace": "sales",
      "contentType": "message",
      "source": "slack"
    }
  ],
  "family": "single_hop",
  "coragExpanded": false,
  "mode": "hybrid",
  "searchTimeMs": 412
}

What matters here:

• answer — grounded prose with inline [n] citation markers.
• citedIndices — which entries in results the answer actually relied on. [1] is the first result: your document.
• answered — true when Honeycomb found enough evidence. When it can't support an answer, it says so rather than guessing.
• confidence — the engine's own estimate of how well-supported the answer is.

Two useful extras as you go deeper: an effort field (low for fast single-pass answers, high for thorough multi-step retrieval), and a ?trace=1 query parameter that attaches a full retrieval trace showing how the answer was assembled. Both are covered in Ask.

Note: When your integration acts on behalf of a specific person — say, a bot answering one employee's question — a key with impersonation enabled passes an x-acting-user header so answers respect that person's access, not the key's. Details in Spaces and permissions.

Troubleshooting

Next steps

You've run the whole loop: ingest, enrich, ask. From here:

• Concepts — entities, facts, memories, Spaces, and how they fit together.
• Ingesting data — batch ingest, file upload, pre-extracted entities, dedup, and superseding stale content.
• Connectors — pipe Slack, email, and other sources in continuously instead of one curl at a time.
• Ask — effort levels, scoped questions, point-in-time queries, and traces.
• Agents and MCP — give your AI agents the same memory through six MCP tools.
• API reference — every endpoint, field by field.