Code

Package code is search and symbols across your repos, for you and your agents.

All API references → · Six flows, four surfaces →


Base URL	`https://api.hanzo.ai`
Operations	7
Auth	`Authorization: Bearer $HANZO_API_KEY`

Answers a question about the caller org's code with a CITED answer: retrieval packs grounding context, then the synthesizer writes the answer over exactly those spans, which come back alongside it.

GET /v1/code/ask

Answers a question about the caller org's code with a CITED answer: retrieval packs grounding context, then the synthesizer writes the answer over exactly those spans, which come back alongside it. It never answers without grounding — with no matched code the answer is empty and says so, and with no synthesizer available the citations still come back with "degraded": true so the caller can reason over the spans itself.

Parameter	In	Type	Required	Description
`q`	query	string	—	Q is the question to answer.
`repo`	query	string	—	Repo narrows retrieval to one repository.

Is askGet with the question in the request BODY, for a question too long or too awkward to put in a URL.

POST /v1/code/ask

Is askGet with the question in the request BODY, for a question too long or too awkward to put in a URL. query and repo in the body take precedence over ?q= and ?repo=; either source works alone.

Request body — application/json (required)

Field	Type	Required	Description
`query`	string	—	Query is the question, from the BODY.
`repo`	string	—	Repo is the repository narrowing, from the BODY.

Packs the most relevant code for a query into a token budget — THE primitive for a coding agent that has to decide what to put in a prompt.

POST /v1/code/context

Packs the most relevant code for a query into a token budget — THE primitive for a coding agent that has to decide what to put in a prompt. It retrieves seed spans, expands each with the definitions it calls and its key callers, then greedily fills the budget, so the answer is a coherent slice of the codebase rather than a list of disconnected matches. The top match is always included, truncated if it alone overflows, so a matched query never comes back empty. A retrieval outage answers 200 with an empty bundle rather than a 5xx.

Request body — application/json (required)

Field	Type	Required	Description
`budgetTokens`	integer	—	BudgetTokens caps the bundle's size.
`query`	string	—	Query is what to retrieve context for.
`repo`	string	—	Repo narrows retrieval to one repository.

Returns the INDEXED content of one file — read_file over the chunks the search tiers hold, for pulling up code an agent just found.

GET /v1/code/file

Returns the INDEXED content of one file — read_file over the chunks the search tiers hold, for pulling up code an agent just found. It is NOT byte-verbatim: the git object plane is the source of record for exact bytes, history and blame. A file absent from the index is a 404, so an agent can tell "not indexed" from "empty file".

Parameter	In	Type	Required	Description
`path`	query	string	—	Path is the file's repo-relative path.
`repo`	query	string	—	Repo is the repository the file belongs to.

(re)indexes a repository for the caller's org, incrementally: files whose content hash is unchanged are skipped, so re-sending a whole tree is cheap.

POST /v1/code/index

(re)indexes a repository for the caller's org, incrementally: files whose content hash is unchanged are skipped, so re-sending a whole tree is cheap. Each file is parsed for symbols, split at AST boundaries and — when the semantic tier is available — embedded, which is what makes it searchable across all three retrieval tiers. Pass prune to also DELETE indexed files absent from the request, which turns the call into a full sync; without it the call is an upsert. The index is written to the caller org's own physically separate database.

Request body — application/json (required)

Field	Type	Required	Description
`files`	cloud_fileInput[]	—	Files is the full set of files to index. Required and non-empty; max 20000 files, 1 MiB per file and 1 GiB in total.
`prune`	boolean	—	Prune deletes indexed files that are NOT in this request — which makes the call a full sync of the repo rather than an u
`repo`	string	—	Repo is the repository label to index under. Required, max 200 bytes.

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).

GET /v1/code/search

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.

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

Returns one repository's file structure with a per-file symbol count — get_repo_structure over the org's own index, with no git checkout involved.

GET /v1/code/tree

Returns one repository's file structure with a per-file symbol count — get_repo_structure over the org's own index, with no git checkout involved. A repository that has not been indexed answers an empty tree rather than an error, so an agent can tell "nothing here" without handling a failure.

Parameter	In	Type	Required	Description
`repo`	query	string	—	Repo is the repository to walk.

All Hanzo APIs · Interactive reference

Code

On this page