API Reference

BioContext7 provides a REST API for searching bioinformatics tools, fetching documentation snippets, and comparing tools programmatically.

Base URL

https://biocontext7.com

All endpoints are relative to this base URL. Responses are JSON unless otherwise noted.

Rate Limiting

Rate limits are per-IP using a token bucket algorithm. When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until the next request is allowed.

Authentication

Most public endpoints require no authentication. Endpoints marked Auth Required return 503 until authentication is enabled.

FastAPI Backend (Python)

When the Python FastAPI backend is deployed, interactive Swagger UI is available at /docs and ReDoc at /redoc with full OpenAPI schema at /openapi.json.

Search & Discovery

Endpoints for searching and ranking bioinformatics tools.

GET/api/search

Search tools

Search the registry of 2,000+ bioinformatics tools by name, keyword, domain, or registry.

Rate limit: 30 requests/minute per IPCache: 5 minutes (s-maxage=300)

Query Parameters

Name	Type	Required	Description
q	string	No	Search query (case-insensitive)
page	integer	No	Page number (default: 1)
sort	string	No	Sort order: "relevance" (default)
domain	string	No	Filter by domain (e.g., "Genomics")
registry	string	No	Filter by registry (e.g., "biotools", "pypi")
organism	string	No	Filter by organism
language	string	No	Filter by programming language
verified	string	No	Filter verified tools ("true"/"false")

Response

Field	Type	Description
results	Tool[]	Array of matching tools
total	integer	Total matching tools across all pages
page	integer	Current page number
pageSize	integer	Results per page (50)

GET /api/search?q=star+alignment&page=1

GET/api/rankings

Tool rankings

Get ranked bioinformatics tools sorted by usage score. Supports filtering by domain and custom sort fields.

Rate limit: 20 requests/minute per IPCache: 1 hour (s-maxage=3600)

Query Parameters

Name	Type	Required	Description
domain	string	No	Filter by domain (e.g., "Genomics")
sortBy	string	No	"rank" (default), "name", "usageCount", "growthPercent"
sortDir	string	No	"desc" (default) or "asc"
page	integer	No	Page number (default: 1, 10 per page)

Response

Field	Type	Description
results	RankedTool[]	Array of ranked tools
total	integer	Total tools matching filter
page	integer	Current page number
totalPages	integer	Total number of pages

GET /api/rankings?page=1&sortBy=rank

GET/api/compare

Compare tools

Compare 2-4 bioinformatics tools side by side. Tools are identified by registry/id format.

Query Parameters

Name	Type	Required	Description
tools	string	Yes	Comma-separated tool keys (e.g., "biotools/star,biotools/hisat2"). Min 2, max 4.

Response

Field	Type	Description
tools	ToolDetail[]	Full details for each found tool
notFound	string[]	Tool keys that could not be resolved

GET /api/compare?tools=biotools%2Fstar%2Cbiotools%2Fsamtools

Documentation

Access tool documentation snippets and search across all indexed documentation.

GET/api/tools/[registry]/[id]/snippets

Tool documentation snippets

Fetch documentation snippets for a specific tool. Tries the backend API first, then falls back to pre-exported static snippet files.

Rate limit: 60 requests/minute per IPCache: 1 hour (s-maxage=3600)

Query Parameters

Name	Type	Required	Description
registry	string	Yes	Tool registry (biotools, pypi, bioconda, bioconductor, dockstore)
id	string	Yes	Tool identifier (alphanumeric with dots, hyphens, underscores)

Response

Field	Type	Description
tool_id	string	Full tool identifier (registry/id)
tool_name	string	Tool display name
snippets	Snippet[]	Documentation snippets with content and metadata
total	integer	Total number of snippets
total_tokens	integer	Total token count across snippets

POST/api/snippets/search

Search documentation snippets

Search across all tool documentation snippets. Proxies to the backend API when configured.

Request Body (JSON)

Name	Type	Required	Description
query	string	Yes	Search query
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 25)

Response

Field	Type	Description
results	SnippetResult[]	Matching documentation snippets
total	integer	Total matching snippets
total_tokens	integer	Total token count
query	string	Echoed search query

Chat

Conversational interface for tool discovery with workflow generation.

POST/api/chat

Chat with tool search

Send natural language queries about bioinformatics tools. Returns tool references and workflow examples for common queries.

Rate limit: 5 queries per session

Request Body (JSON)

Name	Type	Required	Description
message	string	Yes	Chat message (1-2000 characters)
sessionId	string	Yes	Session identifier (alphanumeric, 1-128 chars)

Response

Field	Type	Description
reply.id	string	Unique reply ID
reply.role	"assistant"	Always "assistant"
reply.content	string	Markdown-formatted response
reply.tools	ToolReference[]?	Referenced tools with metadata
reply.workflows	WorkflowStub[]?	Generated workflow code (Nextflow/Snakemake)
remaining	integer	Remaining queries in this session

System

Operational endpoints for health monitoring and repository metadata.

GET/api/health

Health check

Check connectivity status of upstream services (backend API, bio.tools). Always returns 200 — status field indicates "ok" or "degraded".

Response

Field	Type	Description
status	"ok" \| "degraded"	Overall system health
services.backend_api	ServiceStatus	Backend API connectivity (status, latency_ms, error)
services.biotools	ServiceStatus	bio.tools API connectivity (status, latency_ms, error)
config.backend_url_configured	boolean	Whether BIOCONTEXT7_API_URL is set

GET /api/health

GET/api/github/stats

GitHub repository stats

Get GitHub repository statistics (stars, forks, watchers). Cached for 1 hour.

Cache: 1 hour (s-maxage=3600)

Response

Field	Type	Description
stars	integer	Star count
forks	integer	Fork count
watchers	integer	Watcher count

GET /api/github/stats

Tools

Endpoints for tool redirects and citation exports.

GET/api/tools/[registry]/[id]/redirect

Tool redirect lookup

Check if a tool ID has been renamed or moved. Returns the canonical tool location if a redirect exists.

Rate limit: 60 requests/minute per IPCache: 1 hour (s-maxage=3600)

Query Parameters

Name	Type	Required	Description
registry	string	Yes	Tool registry
id	string	Yes	Tool identifier

Response

Field	Type	Description
old_id	string	Original tool identifier (registry:id)
canonical_id	string	Canonical tool identifier
canonical_url	string	URL path to the canonical tool page
redirect_type	string	Redirect reason (rename, merge, etc.)
hops	integer	Number of redirect hops resolved

GET/api/collections/[id]/export

Export collection citations

Export all citations from a tool collection in BibTeX, RIS, or CSL-JSON format. Returns a downloadable file.

Query Parameters

Name	Type	Required	Description
id	string	Yes	Collection identifier
format	string	No	"bibtex" (default), "ris", or "csl-json"

Response

Field	Type	Description
(file)	text/plain	Downloadable citation file with Content-Disposition header

Authenticated Endpoints

These endpoints require authentication and currently return 503 Service Unavailable. They will be enabled when the authentication system is deployed.

Method	Path	Description
POST	/api/submit-tool	Submit a new tool URL for indexing
GET/POST/DELETE	/api/keys	API key management
GET	/api/tasks	List processing tasks
POST	/api/tasks/submit	Submit a documentation URL for processing
GET	/api/dashboard/usage	Usage statistics
GET	/api/dashboard/profile	User profile
GET	/api/dashboard/collections	User collections
GET	/api/dashboard/keys	API key listing
POST/GET/PUT	/api/tools/[registry]/[id]/claim	Claim tool ownership
POST/GET/PUT	/api/tools/[registry]/[id]/admin	Tool administration
POST	/api/tools/[registry]/[id]/dispute	Dispute tool information