Skip to main content

​
Root Endpoint

​
GET /

Get basic API information and version. 
curl http://localhost:8000/
Response: 
{
  "message": "HeartMAP API",
  "version": "1.0.0"
}
​
message
string
API name
​
version
string
API version number

​
Health Check

​
GET /health

Check if the API server is healthy and responsive. 
curl http://localhost:8000/health
Response: 
{
  "status": "healthy"
}
​
status
string
Health status of the server (“healthy” or “unhealthy”)

​
Analyze Data

​
POST /analyze

Upload and analyze single-cell RNA sequencing data. 
curl -X POST http://localhost:8000/analyze \
  -F "file=@heart_data.h5ad" \
  -F "analysis_type=comprehensive" \
  -F "output_format=json"

​
Request Parameters

​
file
file
required
Single-cell data file in .h5ad format (AnnData object)
​
analysis_type
string
default:"comprehensive"
Type of analysis pipeline to runOptions:
  • basic - Quality control and preprocessing
  • advanced_communication - Cell-cell communication analysis
  • multi_chamber - Multi-chamber comparative analysis
  • comprehensive - Complete analysis with all features
​
config_overrides
object
Optional configuration overrides as JSON objectExample:
{
  "min_genes": 200,
  "min_cells": 3
}
​
output_format
string
default:"json"
Format for output resultsOptions:
  • json - JSON format
  • csv - CSV format
  • h5ad - AnnData H5AD format

​
Response

Success Response (200): 
{
  "status": "success",
  "message": "Analysis completed successfully",
  "results": {
    "summary": {
      "n_cells": 15420,
      "analysis_completed": true
    },
    "annotation_summary": {
      "n_cell_types": 12,
      "confidence_scores": {
        "mean": 0.87,
        "median": 0.92
      }
    },
    "communication_summary": {
      "n_interactions": 245,
      "significant_interactions": 87
    },
    "multi_chamber_summary": {
      "chambers_analyzed": ["LV", "RV", "LA", "RA"],
      "chamber_specific_genes": 156
    }
  },
  "output_files": null
}
​
status
string
required
Status of the analysis request (“success” or “error”)
​
message
string
required
Human-readable message about the analysis result
​
results
object
Analysis results object containing summaries and metrics
​
output_files
array
List of output file paths (if any)
Error Response (500): 
{
  "detail": "Error message describing what went wrong"
}

​
Example with Config Overrides

curl -X POST http://localhost:8000/analyze \
  -F "file=@heart_data.h5ad" \
  -F 'request={"analysis_type":"basic","config_overrides":{"min_genes":200,"min_cells":3},"output_format":"json"}'

​
List Models

​
GET /models

Get a list of all available analysis models/pipelines. 
curl http://localhost:8000/models
Response: 
{
  "models": [
    "basic",
    "advanced_communication",
    "multi_chamber",
    "comprehensive"
  ]
}
​
models
array
Array of available analysis model names

​
Get Configuration

​
GET /config

Retrieve the current server configuration. 
curl http://localhost:8000/config
Response: 
{
  "min_genes": 200,
  "min_cells": 3,
  "max_genes": 2500,
  "mt_percent": 5,
  "n_top_genes": 2000,
  "n_neighbors": 15,
  "resolution": 0.8,
  "output_dir": "results",
  "cache_dir": ".cache",
  "temp_dir": "temp"
}
The response contains all current configuration parameters as a dictionary. The exact structure depends on the HeartMAP Config class.

​
Update Configuration

​
POST /config

Update the server configuration at runtime. 
curl -X POST http://localhost:8000/config \
  -H "Content-Type: application/json" \
  -d '{
    "min_genes": 250,
    "min_cells": 5,
    "resolution": 1.0
  }'

​
Request Body

​
config
object
required
Configuration object with parameters to update. Accepts any valid HeartMAP configuration parameters.Common parameters:
  • min_genes (integer): Minimum number of genes per cell
  • min_cells (integer): Minimum number of cells per gene
  • max_genes (integer): Maximum number of genes per cell
  • mt_percent (number): Maximum mitochondrial gene percentage
  • resolution (number): Clustering resolution
Success Response (200): 
{
  "status": "success",
  "message": "Configuration updated"
}
​
status
string
Status of the update request (“success”)
​
message
string
Confirmation message
Error Response (400): 
{
  "detail": "Invalid configuration parameter: invalid_param"
}

​
Error Responses

All endpoints may return error responses with appropriate HTTP status codes:

​
400 Bad Request

Invalid request parameters or malformed request body. 
{
  "detail": "Invalid analysis type: unknown_type"
}

​
500 Internal Server Error

Server-side error during processing. 
{
  "detail": "Analysis failed: insufficient memory"
}

​
Rate Limiting

Currently, there are no rate limits implemented on the API. For production deployments, consider implementing rate limiting using middleware or a reverse proxy.

​
Next Steps

Authentication

Learn about API authentication options

Build docs developers (and LLMs) love

Get started for freeTalk to us