Search code

GET /v1/code/search

Code → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/code/search`
Method	`GET`
Operation	`get_code_search`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Finds code in the caller org's index across three orthogonal retrieval tiers fused by reciprocal-rank fusion: lexical (FTS5 trigram over code-tokenized text), symbolic (real definition and reference edges), and semantic (embedding cosine over AST-boundary chunks). Pick one tier with type, or leave it to run all three as hybrid, which is what a coding agent usually wants. It is FAIL-HONEST: a retrieval outage answers 200 with an empty result set and "degraded": true rather than a 5xx, so an agent degrades instead of stalling. A malformed regex is a 400.

Request

4 fields.

Field	In	Type	Required	Description
`q`	query	string	—	Q is the search query.
`type`	query	string	—	Type selects the retrieval tier: "text" (FTS5 trigram), "regex", "symbol" (definitions), "semantic" (embeddings) or "hybrid".
`repo`	query	string	—	Repo narrows to one repository.
`limit`	query	integer	—	Limit caps how many spans come back: default 20, maximum 100.

Response

Status	Body	Meaning
`200`	code.searchResults	ok
`default`	problem-details	refused

200 body — 15 fields.

Field	In	Type	Always	Description
`capped`	body	boolean	—	Capped is true when the semantic tier stopped at its scan cap — it compares a query with at most 50000 stored vectors — with more left unread, so a chunk past the cap could not be found by meaning.
`degraded`	body	boolean	—	Degraded is true when retrieval failed and the empty result set is an outage rather than a real absence of matches.
`query`	body	string	—	Query echoes the query that was run.
`results`	body	code.Span[]	—	Results are the matching spans, best first.
`results[].endLine`	body	integer (int64)	—	EndLine is the last line of the span, inclusive.
`results[].file`	body	string	—	File is the path inside the repo, relative to its root and never absolute.
`results[].kind`	body	string	—	Kind is what the indexer decided this chunk IS — "func", "method", "type", "struct", "interface", "var", "const", or "block" for a run of code that declares nothing.
`results[].line`	body	integer (int64)	—	Line is where the span starts, 1-based, as an editor counts.
`results[].repo`	body	string	—	Repo is the indexed repository the span was found in, as it was indexed ("owner/name").
`results[].role`	body	string	—	context: match \| definition \| caller
`results[].score`	body	number (double)	—	Score ranks this span against the OTHERS IN THE SAME RESPONSE and means nothing across responses or between tiers: the hybrid tier's number is a reciprocal-rank fusion sum (Σ 1/(60+rank), so tenths at best), the symbol tier's is a descending position count, and the text and semantic tiers pass through bm25 and cosine.
`results[].snippet`	body	string	—	Snippet is the code itself: a bounded excerpt on /search, the whole chunk on /context — which is why the same type serves both and why a /context span is the one an agent pastes into its window.
`results[].symbol`	body	string	—	Symbol is the declared name, when the span declares one.
`results[].tier`	body	string	—	Tier is which retrieval produced the span: "hybrid" (the default — all three fused), "text" (trigram/FTS), "regex", "semantic" (vector), or "symbol".
`type`	body	string	—	Type echoes the retrieval tier that ran, after defaulting.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo code search

.ts

.py

.go

.rs

.java

import { Configuration, CodeApi } from 'hanzoai';

const api = new CodeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getCodeSearch();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import CodeApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = CodeApi(client).get_code_search()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.CodeAPI.GetCodeSearch(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, code_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = code_api::get_code_search(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.CodeApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new CodeApi(client).getCodeSearch();

curl https://api.hanzo.ai/v1/code/search \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool code, op get_code_search — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "code",
         "arguments": {
           "op": "get_code_search",
           "input": {}
         }
       }
     }'

Code API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList file NextList tree