---
title: "Search Kody capabilities, saved packages, integrations, and secret references using natural language or exact user-sc..."
method: GET
path: "/v1/search"
tags: ["search"]
---

# Search Kody capabilities, saved packages, integrations, and secret references using natural language or exact user-sc...

`GET /v1/search`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/search`
- Auth: HTTP bearer

Search Kody capabilities, saved packages, integrations, and secret references using natural language or exact user-scoped package identity. An empty call returns the domain index. Pass "domain" to rank or list one capability domain. Use this inside package and execute runtimes when reusable code needs the same discovery surface as the public MCP search tool.

Org permission: `search:read`.

## Query parameters

- `query` string: Natural language description, or a scoped `@owner/leaf` name, current-origin account package URL, owner-matching hosted package URL, or an exact saved-package UUID (`package_id`) when the name is not known. Optional when "domain" is provided.
- `domain` string: Optional capability domain id (for example "email" or "mcp:linear"). With "query", ranks only that domain's capabilities; without "query", lists the domain's capabilities.
- `limit` integer: Max number of ranked results to return. Defaults to 15.
- `conversationId` string: Optional short conversation identifier. Ties related calls together. If you already have a `conversationId` from an earlier response in the same conversation, pass it back unchanged. Otherwise omit this field to receive a server-generated ID, then reuse the returned `conversationId` on subsequent calls - this enables optimizations like reduced response size. Do not invent your own `conversationId`.
- `includeHiddenPackages` boolean: Include hidden packages in search results (hidden packages are excluded by default).

## Response `200`

Success.

- object
  - `conversationId` string, required
  - `matches` unknown[], required
    - unknown
  - `offline` boolean, required
  - `warnings` string[], required
  - `guidance` string
  - `memories` object
    - `surfaced` unknown[], required
      - unknown
    - `suppressedCount` integer, required
    - `retrievalQuery` string, required
    - `retrieverResults` unknown[]
      - unknown
    - `retrieverWarnings` string[]
  - `telemetry` object: List-mode ranked search telemetry. Omitted when Jev never ran (entity-style short circuits, domain overview, domain browse, exact package identity).
    - `jevRerank` object, required: Jev Score rerank stage for list-mode ranked search. Present when the ranked path ran or skipped the stage. Omitted for domain overview, domain browse, empty discovery, and exact-package identity.
      - `enabled` boolean, required
      - `outcome` 'applied' | 'fallback-error' | 'fallback-timeout' | 'fallback-low-confidence' | 'fallback-empty-after-drop' | 'skipped-offline' | 'skipped-no-ai' | 'skipped-flag-off' | 'skipped-plan' | 'skipped-small-pool' | 'skipped-clear-winner' | 'skipped-empty', required
      - `candidatesBefore` integer, required
      - `candidatesAfter` integer, required
      - `droppedCount` integer, required
      - `meanConfidence` number, nullable, required
      - `top1Type` string, nullable, required
      - `keepPath` 'kept-high' | 'kept-lowered' | 'kept-identity' | 'empty': Adaptive keep path after Jev Score (`kept-high` | `kept-lowered` | `kept-identity` | `empty`). Present when Score ran and mean confidence cleared the floor. `kept-identity` keeps package name, kody id, or leaf hits when every Score misses the floors.
      - `errorReason` string: Short reason when outcome is fallback-error (gateway auth/credits, incomplete Score answers). Omitted otherwise.
      - `model` 'typesafe/jev': Workers AI model when the Jev stage ran or attempted. Omitted when the flag is off.
      - `aiCallCount` integer: Number of Score AI.run calls (one per question batch). Present with model.
      - `usage` object: Summed Workers AI / Gateway token usage across Score batches. Nulls when the binding omitted usage.
        - `inputTokens` number, nullable, required
        - `outputTokens` number, nullable, required
  - `phaseTimings` object: Exclusive Jev rerank wall time in milliseconds when the ranked path computed the stage.
    - `jevRerankMs` number
  - `serverTiming` object[]: Request-scoped phase timings. Same shape as execute serverTiming. Not stored. Includes jevRerank when the Jev stage ran on the ranked path.
    - `name` string, required
    - `durationMs` number, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/705f4f022728?raw)