---
title: Search
kind: resource
slug: search
summary: "Semantic + hybrid knowledge search across everything you can access, cross-Space. Built for agents: returns lightweight pointers to triage, then fetch the few you need."
---

# Search

Semantic + hybrid knowledge search across everything you can access, cross-Space. Built for agents: returns lightweight pointers to triage, then fetch the few you need.

**Knowledge search** finds published Droplets by *meaning* and keyword across **every Space you can access** — not just one. It's the surface for pulling knowledge in and finding source material to synthesize.

It is **two-phase by design**. This endpoint returns lightweight **pointers** — one row per Droplet with a snippet, relevance score, match kind, and a `sizeTokens` budget hint — and does **not** return full document bodies. Triage the pointers, then fetch the full text of only the few you need (e.g. `drop get <slug>`). This keeps an agent's context budget spent on the documents that actually matter.

Results always respect the caller's permissions: every hit is re-checked against the authoritative access gate before any snippet is returned, so nothing you can't read ever surfaces.

Modes: **hybrid** (default — fuses semantic + keyword), **semantic** (concept questions), **lexical** (exact terms). The feature is **user-gated** — ask a sys admin to enable it for your account.

## The Search object

### Attributes

- **`slug`** `string` — Stable identifier of the source Droplet — round-trips to fetch and to citations.
- **`title`** `string` — Droplet display name.
- **`space`** `string | null` — Name of the Space the Droplet lives in.
- **`type`** `string | null` — Droplet type (e.g. DROPLET).
- **`tags`** `string[]` — Tags applied to the Droplet.
- **`ownerEmail`** `string` — Email of the Droplet owner.
- **`updatedAt`** `string` — ISO timestamp of the last deploy — useful for resolving contradictions (newer wins).
- **`score`** `number` — Fused relevance score (higher = more relevant).
- **`matchKind`** `string` — 'semantic', 'lexical', or 'both' — how the result matched.
- **`snippet`** `string` — A short excerpt. Often enough to judge relevance without fetching.
- **`sizeTokens`** `integer` — Rough token estimate of the full Droplet — budget which results to hydrate.

### JSON example

```json
{
  "slug": "data-strategy-may-2026-okr",
  "title": "Data Strategy — May 2026 OKRs",
  "space": "Strategy",
  "type": "DROPLET",
  "tags": ["data", "okr"],
  "ownerEmail": "jonathan.tushman@himarley.com",
  "updatedAt": "2026-05-29T14:00:00.000Z",
  "score": 0.031,
  "matchKind": "both",
  "snippet": "Our data strategy for the quarter centers on three pillars…",
  "sizeTokens": 1840
}
```

## Methods

### Search knowledge across everything you can access

`POST /api/search/knowledge`

Semantic + keyword ("hybrid") search across every published Droplet the caller can access, spanning all their Spaces. Returns lightweight pointers — one row per Droplet with a snippet, relevance score, match kind, and a `sizeTokens` budget hint — NOT full bodies. This is phase one of a two-phase flow: triage these pointers, then fetch the full text of only the few you need via the per-Droplet read path. Results respect the caller's permissions (every hit is re-checked against the authoritative access gate). User-gated: requires the knowledge-search feature to be enabled for the caller.

**Parameters**

- **`query`** _(string · body · required)_ — What to search for.
- **`mode`** _(string · body)_ — Retrieval mode: 'hybrid' (default), 'semantic', or 'lexical'.
- **`limit`** _(number · body)_ — Max results (1–50, default 10).

**CLI**

```bash
drop search knowledge --query "data strategy OKRs" --mode hybrid --limit 10
```

**MCP**

```json
{
  "tool": "drop_search_knowledge",
  "arguments": {
    "query": "data strategy OKRs",
    "mode": "hybrid",
    "limit": 10
  }
}
```

**HTTP**

```bash
curl -X POST 'https://drop.himarley.ai/api/search/knowledge' \
  -H "Authorization: Bearer $DROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"data strategy OKRs","mode":"hybrid","limit":10}'
```

**Response** (200)

```json
{
  "results": [
    {
      "slug": "data-strategy-may-2026-okr",
      "title": "Data Strategy — May 2026 OKRs",
      "space": "Strategy",
      "type": "DROPLET",
      "tags": [
        "data",
        "okr"
      ],
      "ownerEmail": "jonathan.tushman@himarley.com",
      "updatedAt": "2026-05-29T14:00:00.000Z",
      "score": 0.031,
      "matchKind": "both",
      "snippet": "Our data strategy for the quarter centers on three pillars…",
      "sizeTokens": 1840
    }
  ],
  "truncated": false
}
```