Similarity API — Documentation

Similarity search across ~4.8M Logan metagenomic samples. Submit queries by sample ID or custom sketch and retrieve ranked results.

Search Swagger

Submit a search

The "similarity" metric represents the jaccard similarity of the 31-mer sets of the accessions.

POST /search

Search for similar samples using a Logan sample ID or a custom sketch.

Top-k search (by Logan sample ID)

# Synchronous search — blocks until results are ready
curl -X POST "https://similarity.logan-search.org/search" \
     -H "Content-Type: application/json" \
     -d '{"sample_id": "DRR085687", "sync": true, "topk": 10}'

Threshold search — return all neighbors above a similarity

curl -X POST "https://similarity.logan-search.org/search" \
     -H "Content-Type: application/json" \
     -d '{"sample_id": "DRR085687", "sync": true, "min_similarity": 0.8}'

Using a custom sketch

curl -X POST "https://similarity.logan-search.org/search" \
     -H "Content-Type: application/json" \
     -d '{"sketch": "'$(base64 -w0 ./sketch.bin)'", "sync": true, "topk": 10}'

Parameters

Name	Type	Description
sample_id	string	A Logan sample ID to use as query
sketch	string	Base64-encoded sketch binary
topk	int	Number of nearest results to return, default `10`. Ignored when `min_similarity` is set.
min_similarity	float	Return all neighbors with similarity above this threshold instead of the top-k nearest. When set, `topk` is ignored.
sync	bool	If `true`, blocks until results are ready. If `false`, returns a session ID immediately.

Provide either sample_id or sketch, not both. Provide either topk or min_similarity to control result count. Synchronous requests may timeout under heavy load — use async mode for large queries.

Retrieve results

GET /results/{session_id}

Fetch the status and results of a previously submitted search.

curl "https://similarity.logan-search.org/results/sim-2aacd458-5636-4b1c-9f5c-b1f7dc33a95a"

Parameters

Name	Type	Description
metadata	bool	Include main metadata, default `false`
complete	bool	Include all metadata, default `false`

⏳ Running

{
  "session_id": "sim-2aacd458-...",
  "status": "running",
  "results": null,
  "error": null
}

✓ Completed

{
  "session_id": "sim-2aacd458-...",
  "status": "completed",
  "results": {
    "DRR085362": { "score": 1.0, "lower_ci": 0.9982, "upper_ci": 1.0 },
    "DRR085337": { "score": 0.7517, "lower_ci": 0.7281, "upper_ci": 0.7748 },
    "DRR085748": { "score": 0.7496, "lower_ci": 0.7259, "upper_ci": 0.7728 }
  },
  "metadata": { ... },
  "error": null
}

✗ Not found

{
  "detail": "Session 'sim-...' not found or expired."
}

Results are kept for one week after the search completes.

Create your own sketch

To query with a custom sample, you need to compute a sketch in the same format used by the database. The sketching tool is available at:

github.com/RolandFaure/hypervector_database ↗

Follow the instructions in that repository to sketch your FASTA/FASTQ file. The resulting .bin file can then be uploaded directly in the search UI or passed as a base64-encoded string via the API.

The sketch must be generated with the same parameters as the database (sketch size, k-mer length). See the repository for details.

List samples

GET /samples

Paginated list of all available sample IDs.

curl "https://similarity.logan-search.org/samples?offset=0&size=10"

Parameters

Name	Type	Description
offset	int	Starting index, default `0`
size	int	Number of IDs to return, default `100`, max `10000`

✓ Response

{
  "total": 4791208,
  "offset": 0,
  "size": 10,
  "ids": [
    "DRR005282",
    "DRR007367",
    "DRR002746",
    "DRR005002",
    "DRR008107"
  ]
}