API Reference#

This documentation contains the API reference for the MSA Search NIM.

OpenAPI Specification#

You can download or view the OpenAPI specification when the NIM is running:

curl http://localhost:8000/openapi.json

You can also navigate to the interactive API documentation at http://localhost:8000/docs in your browser.

Multiple Sequence Alignment Search#

Endpoint path: /biology/colabfold/msa-search/predict

Request type: POST

Input Parameters#

sequence (string, required): A sequence to search against the MSA databases. Must be a valid protein sequence composed of the 20 standard amino acids (ARNDCQEGHILKMFPSTWYV). Length: 1-4096 characters.

Example:
```
"SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR"
```
databases (list[string], optional): A comma-separated list of database names, to search against (all databases are searched, by default). Accepts 1-3 database names. Default: ["all"].

Examples: ["all"], ["Uniref30_2302"], ["Uniref30_2302", "PDB70_220313"]
search_type (string, optional): Which type of MSA Search to run for alignment production. Default: "colabfold".

Options:
- "colabfold": Cascaded search with higher sensitivity
- "alphafold2": Single-pass iterative search
Examples: "colabfold", "alphafold2"
e_value (float, optional): The e-value threshold for filtering hits when building the Multiple Sequence Alignment. Sequences with an e-value greater than this are not included in the MSA. Range: 0.0-1.0. Default: 0.0001.
iterations (int, optional): The number of MSA iterations to perform, where more iterations find more distant homologs. Range: 1-6. Default: 1. Note: For cascaded search (search_type="colabfold"), the number of iterations is fixed to 3 and this parameter is ignored.
max_msa_sequences (int, optional): The maximum sequences taken from the MSA for model prediction. Range: 1-10001. Default: 500. Note: When GPU Server is enabled (default in version 2.0.0), this parameter must be set globally via the NIM_GLOBAL_MAX_MSA_DEPTH environment variable at container startup.
output_alignment_formats (list[string], optional): The output format of the MSA. Supported formats: "a3m", "fasta". Default: ["a3m"].

Examples: ["a3m"], ["a3m", "fasta"]

Outputs#

alignments (Dictionary[string → Dictionary[string → AlignmentFileRecord]]): The MSA alignments organized by database and format. Structure: {database_name: {format: AlignmentFileRecord}}. For example, alignments['Uniref30_2302']['a3m'] contains the A3M alignment for the Uniref30 database.

Each AlignmentFileRecord contains:
- alignment (string): The contents of a single MSA. For ‘a3m’ format, sequences are in compact A3M format with insertions in lowercase. For ‘fasta’ format, sequences are in standard aligned FASTA format with gaps.
- format (string): The format of the alignment record(s). Values: "a3m" or "fasta".
Example response:
```
{
  "alignments": {
    "Uniref30_2302": {
      "a3m": {
        "alignment": ">query\nMVPSAGQLALFALGIVLAACQALENS\n>hit1\nMVPSAGQLALFALGIV---CQALENS\n>hit2\nMVPSAGQLALF-LGIV---CQALENS",
        "format": "a3m"
      }
    }
  },
  "metrics": {}
}
```
To access the A3M-formatted alignment for the Uniref30_2302 database:
```
alignments["Uniref30_2302"]["a3m"]["alignment"]
```
metrics (dictionary, optional): Contains information about the response useful for debugging and measuring performance. May be empty or null.

Get Database Configuration#

Endpoint path: /biology/colabfold/msa-search/config/msa-database-configs

Request type: GET

Input Parameters#

None.

Outputs#

configs (dictionary): A nested dictionary containing information about all configured MSA databases. The configuration can be converted to YAML format to view the original database configuration.

Get MMSeqs2 Version#

Endpoint path: /biology/colabfold/msa-search/mmseqs2/version

Request type: GET

Input Parameters#

None.

Outputs#

Returns version information for the MMSeqs2 installation used by the NIM.

Note

Use this endpoint to get the exact MMSeqs2 version when you need to create custom database indices. Custom indices must be created with the same MMSeqs2 version as the one running in the NIM to ensure compatibility.

Health Endpoints#

Readiness Check#

Endpoint path: /v1/health/ready

Request type: GET

Description: Checks if the service is ready to handle requests.

Outputs#

Status code 200: Service is ready
Status code 503: Service is not ready

Response includes a JSON object with:

message (string): Status message
object (string): Always “health.response”
status (string, optional): Status string for backwards compatibility

Liveness Check#

Endpoint path: /v1/health/live

Request type: GET

Description: Checks if the service is live (running).

Outputs#

Status code 200: Service is live
Status code 503: Service is not live

Response format is the same as the readiness check.

NIM Metadata Endpoints#

Version#

Endpoint path: /v1/version

Request type: GET

Description: Returns version information for the NIM.

Outputs#

release (string): The product release version of the NIM
api (string): The server API version running inside the NIM

License#

Endpoint path: /v1/license

Request type: GET

Description: Returns license information for the NIM.

Outputs#

name (string): The name of the license
path (string): The filepath within the container containing the license content
sha (string): SHA1 hash of the license contents
size (integer): Number of characters in the license content
url (string): URL where the license is hosted externally
type (string): Always “file”
content (string): The full license text

Metadata#

Endpoint path: /v1/metadata

Request type: GET

Description: Returns comprehensive metadata about the NIM deployment.

Outputs#

assetInfo (list[string]): Required container assets excluding model artifacts
licenseInfo (LicenseEndpointModel): License information
modelInfo (list[ModelInfo]): Information about models being served
repository_override (string): Alternate location for retrieving artifacts
version (string): NIM service version
selectedModelProfileId (string): ID of the currently selected model profile

Manifest#

Endpoint path: /v1/manifest

Request type: GET

Description: Returns the manifest file describing required model artifacts.

Outputs#

manifest_file (string): Content of the manifest file
repository_override (string): Alternate location for retrieving artifacts

Metrics#

Endpoint path: /v1/metrics

Request type: GET

Description: Exposes Prometheus metrics for monitoring.

Outputs#

Returns metrics in Prometheus format.