This document describes the BSimVis backend REST API. The API is built with Flask-RESTX; interactive Swagger UI is available at /api/.
All endpoints are prefixed with /api. Unless noted, collection defaults to main; the file, function, similarity and bin_sim search endpoints instead require either collection or pool and return 400 without one. Most read endpoints accept offset/limit pagination and a format (json or csv) export parameter.
- Index & Config
- Jobs
- Collections & Batches
- Files
- Functions
- Features
- Feature Indexing
- Search Utilities
- Similarity Engine
- Function Clusters
- Binary Similarity
- Binary Clusters
- Diff
- Tags
- Notes
- LLM
- Pools (Cross-Collection)
- Searches
Database index statistics and counts.
- Params:
collection,details(true/false). - Returns:
num_files,num_functions,num_indexed,num_missing,num_features,num_sim_meta,indexing_ratio. Withdetails=true, adds acomponentsbreakdown (key pattern, count, average size).
Returns default configuration values from bsimvis_config.toml.
- Returns:
clustering(engine,bin_engine,uf_threshold,bin_uf_threshold,cohesion_cut,epsilon,min_cluster_size,min_samples,selection_method,min_sim,min_features,min_cohesion,idle_debounce_seconds) andsimilarity(top_k,min_score,min_features,algo).
Instance-wide counters (files, functions, collections, pools) plus job queue health. Cheap and uncached.
Heavier homepage panels: top tags, biggest binary clusters, recent batches. Cached 120s in-process.
- Params:
refresh=trueto bypass the cache.
Lists Ghidra language IDs seen across the instance and the compiler specs valid for each.
Lists recent and active background jobs.
- Params:
limit(default 100),offset,collection,pool(aliaspool_id),status,type. - Returns:
items,total.
Aggregate metrics across all jobs (total, completed, failed, pending).
Detailed status and logs for a job or pipeline.
Cancels a pending or running job/pipeline.
Cancels all pending or running jobs and pipelines.
Retries a failed or cancelled job/pipeline (pipelines reset all sub-tasks).
Fleet-level pause/resume. GET returns whether the fleet is paused. POST pauses it — workers finish their current job and claim no more. DELETE resumes it.
Per-job pause/resume. Pauses one job, group or pipeline without affecting the rest of the fleet. A running leaf finishes first; nothing underneath the paused job is claimed again until it is resumed.
Lists and searches collections with filtering and CSV/JSON export.
- Params:
q,name,sort_by(name|total_files|total_functions|total_batches|last_updated),sort_order,min_files/max_files,min_functions/max_functions,min_batches/max_batches,min_last_updated/max_last_updated,offset,limit,format.
Wipes and deletes a collection entirely (async background job).
- Body:
collection(required).
Cleans up temporary raw/JSON upload keys in a collection (async background job).
- Body:
collection(required).
Lists and searches ingestion batches in a collection.
- Params:
collection(required),q,offset,limit,format.
Searches files with rich filtering, sorting, and export. Accepts pool to target a cross-collection pool instead of a collection.
- Core:
collectionorpool,q,file_name,file_md5(aliasmd5),language_id(aliaslanguage),batch_uuid. - Threat-intel metadata:
first_seen,last_seen,filetype,avtype,yara,cc_ip,file_names,note_owner(aliasnote_owners), and the clustering-derivedinferred_yara,inferred_avtype,inferred_filetype,inferred_ccip,inferred_filename,inferred_md5. - Cluster:
bin_cluster_uuid,bin_cluster_name,min_cohesion/max_cohesion,algo. - Tags:
tag,static_tag,user_tag,file_tag,file_static_tag,file_user_tag, plus anexclude_-prefixed variant of each. All tag filters are repeatable. - Ranges:
min_function_count/max_function_count,min_bsim_features/max_bsim_features,min_entry_date/max_entry_date. - Paging/sort:
sort_by(numeric:function_count|bsim_features_count|cohesion_score|entry_date|file_date; text:file_name(default) |parent_file_name|related_file_name|language_id|filetype|avtype),sort_order(defaultasc),offset,limit,format.
file_md5/md5 and file_name match the file's own value or its parent_md5/related_md5 and parent_file_name/related_file_name, so a lookup by a parent archive hash or name also returns its children.
Full metadata for a file including its clusters.
- Params:
collection,algo.
Full call graph for a file.
- Params:
collection,file_md5.
Uploads a raw binary for server-side Ghidra analysis. One job does analysis,
indexing, and (unless skip_sim) per-file similarity build, all in-process —
no follow-up call is needed for the file's own data. Params accepted as query or form.
- Config:
collection,file_name,profile(fast/full),min_func_len(default 10),processor(force Ghidra Language ID),cspec(force Compiler Spec ID). - Similarity:
algo(jaccard/unweighted_cosine/milvus_sparse),top_k,min_score,min_features,skip_sim. - Metadata:
batch_uuid(generated server-side if omitted, kept for tagging/lookup — no longer required for batching, see below),batch_name(defaultGhidra Batch),tags(repeatable),related_md5(repeatable),file_metadata_extra(JSON object merged into the file document — this is howparent_md5,parent_file_nameandrelated_file_nameare supplied; all four parent/related fields are indexed and searchable at file, function and similarity level). - Scheduling:
enqueue(defaulttrue;falsecreates the job without starting it).priority(highto jump this file's analysis ahead of other pending jobs on the shared worker pool; doesn't preempt a job already running). - Clustering: every upload is recorded in its collection's job lane; once uploads to that collection go quiet (
clustering.idle_debounce_seconds, default 30s), the lane automatically clears and rebuilds that collection's function/binary clusters covering everything uploaded since the last rebuild. SeePOST /api/cluster/rebuild_allandPOST /api/file/upload/batch_finalizeto force this immediately instead. - Returns:
status,file_md5,pipeline_id,batch_uuid.
Uploads pre-analyzed JSON metadata + function feature maps from client-side extractors.
- Body:
collection,file_md5(optional, computed if missing or read fromfile_metadata),top_k,min_score,min_features,algo,skip_sim,skip_write,batch_uuid,enqueue, plus the standard extractor payload. Similarity defaults fall back tobsimvis_config.toml(similarity.*) when omitted. file_metadatacarries the file document:file_name,language_id,parent_md5,parent_file_name,related_md5,related_file_name, threat-intel fields (yara,avtype,filetype,cc_ip,first_seen,last_seen,file_names), …- Params:
enqueue(query param overrides the body; defaults tofalsewhen abatch_uuidis present,trueotherwise).
Uploads a chunk of function analysis data (streaming path to avoid memory bloat).
Finalizes a multi-file batch upload by orchestrating a master pipeline. Optional now
that uploads auto-cluster on their own after a quiet period (see POST /api/file/upload)
— use this to force it immediately for an explicit set of pipeline/job ids instead of
waiting. Submitted through the collection's job lane: queues behind whatever's currently
active for that collection rather than running concurrently with it (two overlapping
finalize/rebuild calls used to race and corrupt each other's cluster/bin_sim results).
- Body:
pipeline_ids(required),batch_uuid,collection,algo,skip_sim,min_cohesion,priority(highto jump ahead of other rebuilds already queued for this collection). - Returns:
status("queued"),master_pipeline_id,batch_uuid.master_pipeline_idis pollable viaGET /api/jobs/{id}whether it started immediately or is waiting on another active rebuild.
Partially updates metadata for a file and triggers propagation.
- Body:
collection,metadata(dict of fields to update).
Returns the containment lineage of a file: the containers it was extracted from (nearest first) and the files extracted from it. Each node carries an exists flag (false for a container that was declared but never uploaded).
- Params:
collection.
Stages a batch's MD5 → metadata map. Uploads in that batch resolve their own metadata by hash, including binaries that only exist after server-side unpacking (archive members, UPX payloads, GPR programs).
- Body:
collection,batch_uuid,metadata(dict of MD5 → metadata dict).
Bulk metadata update + propagation.
- Body:
collection,updates(map of MD5 → metadata dict).
Searches functions with rich filtering, sorting, and export. Accepts pool to target a cross-collection pool.
- Core:
collectionorpool,q,function_name(aliasname),file_md5(aliasmd5),file_name,language_id(aliaslanguage),namespace,return_type(aliasret_type),entrypoint_address(aliasaddress),calling_convention,parameters,decompiler_id,batch_uuid,note_owners(aliasnote_owner). - Cluster:
cluster_id,cluster_uuid,cluster_name,cluster_stability. - Inherited file metadata:
first_seen,last_seen,filetype,avtype,yara,cc_ip,file_names,type,entry_date,file_date— indexed at function level and filterable here. - Tags:
tag,static_tag,user_tag, andfunc_/file_-scoped variants, each with anexclude_counterpart. Repeatable. - Filters:
min_features,min_cohesion(default 0.95 — clusters below the threshold are dropped from the response). - Paging/sort:
sort_by(id(default) or a numeric function-level index:bsim_features_count|instruction_count|entry_date|file_date|batch_order|cluster_stability),sort_order(defaultdesc),offset,limit,pool_limit(default 1000000),format.
As on file/search, file_md5/md5 and file_name also match the file's parent_md5/related_md5 and parent_file_name/related_file_name.
Decompiler tokens and metadata for a function.
- Params:
id(idx:coll:func:md5:addr). - Returns:
rows(line objects with tokens),tips(features per token),meta.
Unified diff endpoint (alias of /api/diff). Without addr_a/addr_b returns the file-level bin_sim doc; with them, a side-by-side aligned function diff. See Diff for the full parameter list.
Lists all BSim features for a function with their code context.
- Params:
id.
Call graph for a function: callers and callees with function metadata.
- Params:
collection,id.
Bulk relation lookup for a set of function IDs across call and similarity edges.
- Params:
collection,id(repeatable),algo.
Searches BSim features and their frequency across a collection.
- Params:
collection,q,hash(hex prefix),type,op,min_frequency/max_frequency,min_tf_score/max_tf_score,sort_by(aliassort, defaulttf_score),sort_order(aliasorder, defaultdesc),offset,limit(default 20),format.
All function occurrences for a specific feature hash.
- Params:
collection,offset,limit(default 1000).
Manages the searchable global feature index (distinct from per-function feature vectors).
Feature indexing status. Params: collection, details.
Indexing status per file. Params: collection.
Enqueues a feature indexing job. Body: collection (required), md5 or batch.
Enqueues a feature clear job. Body: collection (required), md5 or batch.
Autocomplete for indexed metadata field values.
- Params:
collectionorpool,level(func/file/sim),field(e.g.function_name),q(prefix),limit(default 50).
Cardinality stats for metadata fields.
- Params:
collection,level,field(list).
Ctrl+K palette backend. Searches all entity types (files, functions, similarities, clusters, pools, collections) by a free-text query string.
- Params:
q(required),collection,limit.
SSE streaming variant of /api/search/unified. Returns results as server-sent events as each entity type resolves, so the palette can start populating before all types finish.
- Params: same as unified.
Main function-level similarity search with rich filtering, cross-binary detection, caching, and export. Accepts pool.
- Core:
collectionorpool,algo(defaultunweighted_cosine),min_score(default fromsimilarity.min_score, 0.9),max_score(default 1.0),q. - Metadata:
name,file_name,md5(repeatable),id,language,namespace,ret_type,address,batch_uuid. As on the other search endpoints,md5andfile_namealso match the file's parent/related md5 and file names. - Tags:
tag,static_tag,user_tag, plussim_/func_/file_-scoped variants, each with anexclude_counterpart. Repeatable. - Behavior:
cross_binary(true/false),match_mode(any/both, defaultany),min_features,min_cohesion(default 0.95),pool_limit. - Paging/sort/cache:
sort_by(score(default) /feat_count),sort_order(defaultdesc),offset,limit,use_cache(defaultfalse),format. - Returns:
pairs(withmeta1/meta2),total,offset,limit.
Similarity score and tags for a specific function pair.
- Params:
id1(required),id2(required).
Lists pre-calculated similarity results for a file or batch.
- Params:
collection,md5(required unlessbatch),batch(required unlessmd5),algo,limit(default 20),offset.
Build status (total vs built) for a target.
- Params:
collection(required),md5orbatch,algo.
Build status grouped by batch or file.
- Params:
collection(required),by(batch/md5, defaultbatch),algo.
Enqueues a job to pre-calculate similarity pairs.
- Body:
collection(required),md5,batch,algo,min_score,top_k,min_features,all(defaultfalse),skip_write. One ofmd5,batchorallis required; omitted algo/score/top_k/min_features fall back tobsimvis_config.toml(similarity.*).
Enqueues a clear + build pipeline. Same body as build.
Enqueues a similarity clear job.
- Body:
collection(required),md5,batch,algo.
Adds/removes a user tag on a similarity pair.
- Body:
collection,id1,id2,algo,tag.
Clustering of functions by similarity. The default engine is threshold_uf (deterministic union-find); hierarchical_uf builds a full single-linkage hierarchy; hdbscan is the legacy path. All three are configured via bsimvis_config.toml [clustering].
Enqueues a clustering job.
- Body:
collection,algo,engine(threshold_uf/hierarchical_uf/hdbscan, default from config),uf_threshold(default from config),cohesion_cut(default from config),min_cluster_size(default 2),min_samples(default 1),epsilon(default 0.1),selection_method(defaulteom),min_sim(default 0.0),min_features(default 0). The HDBSCAN-specific params (epsilon,min_samples,selection_method) are ignored whenengine=threshold_uf.
Clear + cluster pipeline (function clusters only, no bin_sim rebuild). Same body as
build, plus priority (high to jump ahead of other rebuilds already queued for this
collection). Submitted through the collection's job lane — see rebuild_all below.
Full re-analysis pipeline: clear + function clusters + binary similarity + binary
clusters. Same body as build, plus priority. Submitted through the collection's job
lane: at most one rebuild runs per (collection, algo) at a time — a second call while
one is active queues behind it instead of racing it (this used to corrupt cluster/bin_sim
results when two rebuilds overlapped). Also fires automatically after uploads to a
collection go quiet, so this endpoint is for forcing it now, not required routine
maintenance. Returns {"job_id", "pipeline_id", "status": "queued"} — pipeline_id is
pollable via GET /api/jobs/{id} whether it started immediately or is waiting.
Enqueues a cluster clear job. Body: collection, algo.
Lists clusters with metadata and filtering.
- Params:
collectionorpool,algo,min_stability/max_stability,min_count/max_count,min_features/max_features,min_cohesion/max_cohesion,sort_by(count/stability/features/cohesion),sort_order,q,cluster_id,cluster_uuid,cluster_name,func_name,func_addr,file_name,show_members,show_parents,show_children,offset,limit,format. - Cluster membership excludes points shed as noise by HDBSCAN.
Condensed dendrogram tree for D3 visualization. Params: collection, algo.
Function IDs in a cluster. Params: collection, algo, cluster_id, limit, offset.
Sample of function metadata for a cluster UUID. Params: collection, algo, cluster_uuid, limit, offset.
Updates cluster metadata (e.g. rename).
- Body:
collection,algo,cluster_id,cluster_name.
File-level similarity derived from shared function clusters.
Enqueues a job to build binary similarities.
- Body:
collection,algo,md5_a,md5_b,min_cohesion(default 0.5).
Clear + build pipeline. Same body as build.
Recomputes the tag split (Code / Library / Content score axes) of stored binary similarity pairs without triggering a full rebuild. Useful after tag changes that affect the score decomposition.
- Body:
collection,algo.
Clears binary similarities. Body: collection, algo, md5.
Pre-calculated similar binaries for a given MD5.
- Params:
collection,algo,md5,limit,offset.
Searches binary similarity pairs with filtering and sorting. Accepts pool.
- Core:
collectionorpool,algo(defaultunweighted_cosine),q,md5(matches either side, and also the sides'parent_md5/related_md5),file_name(either side, plus parent/related file names),arch(architecture / language ID, either side). - Ranges:
min_score/max_score,min_coverage/max_coverage,min_shared/max_shared,min_funcs/max_funcs(function count). - Tags:
file_tag,exclude_file_tag,exclude_file_static_tag,exclude_file_user_tag(resolved through the live file tag index, so tag edits take effect without a rebuild), plus similarity-leveltag,exclude_tag,exclude_static_tag,exclude_user_tag(applied on the page). All repeatable. - Paging/sort:
sort_by(aliassort;score(default),coverage,shared_clusters,functions_count,computed_at,architecture),sort_order(defaultdesc),offset,limit(default 50). - Returns:
total,offset,limit,results— each pair enriched withmd5_a/md5_b,coll_a/coll_b,file_name_a/file_name_b, thefile_parent_*/file_related_*md5 and name fields,file_tags_*/file_user_tags_*,architecture_*,functions_count_*,compiler_*,entry_date_*,coverage_a/coverage_b,shared_clusters. - Pool search uses the pool's own bin_sim index when present; otherwise it falls back to a slower full scan (run
bin_sim/reindexwithpool_idto build it).
Same unified diff behavior as /api/diff, plus algo. See Diff for filters, table paging and view=sankey.
Rebuilds secondary indexes for existing binary similarity pairs (backfill).
- Body:
collection,algo,pool_id(optional — index a pool to enable fast pool search).
HDBSCAN-based clustering of binaries.
Enqueues a binary clustering job.
- Body:
collection,algo,min_cluster_size(default 2),min_samples(default 1),epsilon(default 0.1),selection_method(defaulteom),min_sim(default 0.0).
Clear + cluster pipeline. Same body as build.
Clears binary clusters. Body: collection, algo.
Lists binary clusters. Params: collection or pool, algo, min_stability/max_stability, min_count/max_count, min_cohesion/max_cohesion, sort_by (count/stability/cohesion), sort_order, q, cluster_id, cluster_uuid, cluster_name, file_name, file_md5, show_members, show_parents, show_children, offset, limit, format.
Condensed tree for binary clustering. Params: collection, algo.
File IDs in a binary cluster. Params: collection, algo, cluster_id, limit, offset.
Sample of file metadata for a cluster UUID. Params: collection, algo, cluster_uuid, limit, offset.
Updates binary cluster metadata (e.g. rename).
- Body:
collection,algo,cluster_id,cluster_name.
Unified diff endpoint. Without addr_a/addr_b returns the file-level bin_sim document; with them returns a side-by-side aligned function code diff. /api/function/diff and /api/bin_sim/diff are aliases of this endpoint (the latter also reads algo, default unweighted_cosine).
- Params:
collection_a(aliascollection, defaultmain),collection_b(aliascoll_b, defaults tocollection_a),md5_a,md5_b,addr_a,addr_b,pool(aliaspool_id).md5A/md5B/addrA/addrBand the legacyid1/id2function-ID pair are also accepted. - Function diff returns:
rows(aligned left/right),left_tips/right_tips,meta1/meta2. - File diff returns:
score,file_metadata_a/file_metadata_b,functions_metadata(per function ID), anddiffwith thematched,unique_to_aandunique_to_btables. Matched/unique rows carrycluster_uuid,cluster_name,cohesion,similarity,avg_features,sim_rarity,is_clustered.
Adding table returns one filtered/sorted page of a single diff table instead of the whole document.
table:matched|unique_to_a|unique_to_b.- Filters:
q(function name, namespace, address, tags),cl_q(cluster name; unclustered rows matchunclustered),note_a/note_b/note(note owner —note_a/note_bon matched rows,noteon unique rows),sim_min/sim_max,feat_min/feat_max(average features),rar_min/rar_max(similarity rarity). - Sort/paging:
sort_col(any row field, plusfunc_namewhich resolves the name from metadata),sort_dir(asc/desc, defaultdesc),offset,limit(default 100;0or less returns everything fromoffset). - Returns:
items,total,offset,limit,table,functions_metadata(page rows only),file_metadata_a/file_metadata_b.
view=sankey returns a compact projection for the Sankey visualization: score, file_metadata_a/file_metadata_b, counts (per table), and sankey with cluster fields plus inlined feature counts (feat_a/feat_b for matched rows, feat for unique rows) — no names, tags or notes, so large binaries stay renderable. Ignored when table is present.
Tags apply to files, functions, and similarities. Each entity carries static (analysis-derived) and user tags. The read endpoints (/api/tags, /api/tags/metadata, /api/tags/stats) accept pool (alias pool_id) in place of collection. Tags and notes are stored on the origin collection and mirrored into every pool containing it.
Global tag index (all tags with colors and priorities). Params: collection (required).
Adds/removes a tag on one entity.
- Body:
collection,entity_type(file/function/similarity),entity_id,tag.
Same as above but entity_ids is a list.
All tag metadata for a collection. Params: collection.
Statistics for a specific tag. Params: collection, tag.
Sets a tag color. Body: collection, tag, color (e.g. #ff0000).
Sets a tag priority. Body: collection, tag, priority (int).
Returns the parameters used to derive tag colours (namespaces, special values, priority table).
Lists the tag vocabulary with usage counts and the LLM flag.
- Params:
collection(required),q(substring filter),sort_by(tag/priority/total_count/function_count),sort_order.
Creates a tag in the vocabulary without tagging any entity.
- Body:
collection,tag,color(optional),priority(optional),llm(bool — include in LLM tag vocabulary, optional).
Deletes a tag and strips it from every entity carrying it.
- Body:
collection,tag.
Includes or excludes a tag from the LLM tagging vocabulary.
- Body:
collection,tag,llm(bool).
Returns the rule each analysis tag came from, with a link to its source.
- Params:
tag(repeatable), ortags(comma-separated).
Returns one rule's own source text, read from the mirror on disk.
- Params:
id(rule id as returned by/tags/provenance).
Returns match metadata (which rules matched) for a list of entities.
- Body:
collection,entity_ids(list).
Analyst notes on functions, files, and binary similarity pairs. The list endpoints accept pool (alias pool_id) in place of collection.
POST /api/notes/add— Body:collection,func_id,text,owner.PUT /api/notes/update— Body:collection,func_id,note_id,text.DELETE /api/notes/remove— Body:collection,func_id,note_id.GET /api/notes/list— Params:collection,func_id.
POST /api/notes/file/add— Body:collection,file_id,text,owner.PUT /api/notes/file/update— Body:collection,file_id,note_id,text.DELETE /api/notes/file/remove— Body:collection,file_id,note_id.GET /api/notes/file/list— Params:collection,file_id.
POST /api/notes/bin_sim/add— Body:collection,md5_a,md5_b,algo,text,owner.PUT /api/notes/bin_sim/update— Body:collection,md5_a,md5_b,algo,note_id,text.DELETE /api/notes/bin_sim/remove— Body:collection,md5_a,md5_b,algo,note_id.GET /api/notes/bin_sim/list— Params:collection,md5_a,md5_b,algo.
Local LLM integration (Ollama). Configure the model and system prompt in bsimvis_config.toml [llm].
Generates a summary for a function.
- Body:
func_id(required),prompt,code,func_name(all optional).
Continues a discussion about a function.
- Body:
messages(list of{role, content}).
Streams a threat-intel summary for a binary using all available metadata.
- Body:
file_id.
Starts a background LLM enrichment job (notes and/or tags) over a set of functions.
- Body:
collection(required),func_ids(list) orfilters(function-search query string),actions(["notes", "tags"]),overwrite(defaultfalse),custom_prompt,tag_vocabulary. - Returns:
job_id.
Progress, per-function state and errors for an LLM batch job.
Cancels an LLM batch job.
Starts a new interactive analyst chat session with tool access to the collection (function lookup, call graph, similarity, tags).
- Body:
collection(required),pool(alternative),system_prompt(optional override),context(optional — appended to the system prompt, e.g. to scope the session to a specific function). - Returns:
session_id.
Returns the message history for a chat session.
Sends an analyst message. The model may call tools to look up functions, call graph, similarity, and tags before answering. Streams one NDJSON event per line as each tool call resolves, then a final done (or error) event with the reply.
- Body:
message(required).
Starts a background context-aware LLM tagging job: partitions the selection by call-graph locality (bottom-up, mutually-recursive groups combined) instead of judging each function in isolation.
- Body:
collection(required),func_idsorfilters,actions,overwrite,custom_prompt,unit_max_size(max functions per LLM call for a connected cluster, default 5).
Progress/cancel for a contextual batch job.
Starts agentic LLM analysis for one file or every file in a collection.
- Body:
collection(required),pool(alternative),file_md5(omit to analyse every file),actions,overwrite,skip_fid_tagged(defaulttrue),min_complexity,custom_prompt.
Progress/cancel for a file-analysis job.
Analyses differences, similarities and malicious functions in one binary pair.
- Body:
collection(required),coll_b,md5_a(required),md5_b(required),pool,algo,threshold(default 0.9),include_unique(defaulttrue),include_unchanged(defaultfalse),skip_fid_tagged(defaulttrue),min_complexity,max_functions(0 = unlimited),actions,overwrite,custom_prompt.
A pool groups multiple collections so similarity and clustering can run across their combined function/binary set. Search endpoints that accept a pool parameter (file/search, function/search, similarity/search, bin_sim/search, search/autocomplete, cluster/list, bin_cluster/list, tags, notes, diff) target the pool instead of a single collection. Passing both pool and collection scopes the request to that one member collection within the pool.
Clustering artifacts (cluster_*, bin_cluster_*, inferred_*) are namespace-local: a pool's clusters are computed from the pool's own similarity graph and are never merged in from member collections. Tags and notes are the opposite — they live on the origin collection and are mirrored into every pool that contains it.
Lists and searches pools.
- Params:
collection(membership filter),q(name / id / member collections / sync status),name,id,sync_status(current/outdated/created),sort_by(name/id/created_at/last_built_at/sync_status/count fields),sort_order,offset,limit(default 100),refresh_sync(1 = recompute live status, slower),min_created_at/max_created_at,min_last_built_at/max_last_built_at, plusmin_/max_ranges on the count fields (total_func_similarities,total_func_clusters,total_file_similarities,total_file_clusters,total_files,total_functions). - Returns:
pools,total,offset,limit. Default order iscreated_atdescending.
Creates a pool definition and enqueues the full build pipeline (per-file similarity build → finalize → function clustering → binary similarity → binary clustering → index).
- Body:
pool_id(optional, generated if missing),name(required),collections(required list),config(optional):only_cross_collection(defaultfalse) — when true, pool similarity keeps only pairs whose two functions come from different member collections. Use it to identify known functions across collections (e.g. label an unknown binary against a reference corpus) instead of paying for full cross-correlation, including the within-collection pairs each collection already has.func_sim_params:algo(defaultunweighted_cosine),top_k(default 1000),min_score(default 0.3),min_features(default 0),skip_write(benchmark-only: compute without persisting pairs)func_cluster_params:cluster_algo(defaulthdbscan),min_cluster_size(default 2),min_samples(default 1),epsilon(default 0.1),selection_method(defaulteom)file_sim_params:enabled(defaulttrue),min_cohesion(default 0.5)file_cluster_params:min_cluster_size(default 2),min_samples(default 1),epsilon(default 0.1),selection_method(defaulteom)- Legacy flat fallbacks, still written and read when the structured params are absent:
algo,top_k,min_score,cluster_algo,cluster_params,skip_write.
- Returns:
message,pool_id,job_id(the pipeline).
Pool details: name, collections, status, sync_status, created_at, last_built_at, only_cross_collection, the four *_params objects, sync_snapshots, and the total_* counts.
Renames a pool. Body: name.
Deletes a pool and all its data.
Enqueues the same build pipeline as pool creation (similarities → clusters → binary similarities → binary clusters → index) without wiping existing data. Returns job_id.
Clears the pool's function clusters, binary similarities and binary clusters, then enqueues clustering → binary similarity → binary clustering → index. Returns job_id.
Wipes all computed pool data and enqueues the full build pipeline. Returns message, pool_id, job_id.
Checks whether the pool is outdated compared to its source collections.
Fast LLM-powered relevance triage searches scoped to a collection, a single file, an arbitrary function filter, or a binary pair diff. Results are ranked yes / maybe / no and can be tagged or handed off to the deep-analysis pipeline.
Lists past searches, most recent first.
- Params:
offset,limit(default 50).
Resolves the given scope to a function set and starts a fast relevance-triage classification job.
- Body:
collection(required),pool(alternative).query(required) — free-text description of what the analyst is looking for.name(optional, defaults to the query text).scope(required):type:collection|file|filter|pair- For
file:md5,skip_fid_tagged(defaulttrue). - For
filter:filters(function-search query string). - For
pair:md5_a,md5_b,coll_b,pool_id,algo,state(all/matched/unique/changed),threshold,include_unique,include_unchanged,skip_fid_tagged,min_complexity,max_functions.
- Returns:
search_id,job_id.
Returns the search's metadata, merging live job status while it is still running.
Deletes a search (cancels its job first if still running).
Ranked results for a completed search.
- Params:
offset,limit(default 100),verdict(repeatable:yes/maybe/no).
Directly tags the given functions (synchronous, no background job).
- Body:
func_ids(list, required),tag(required).
Hands the given functions to the deep contextual-batch analysis pipeline (notes/tags) as a normal LLM_CONTEXTUAL_BATCH job.
- Body:
func_ids(list, required),actions,overwrite,custom_prompt(defaults to the search's own query).