> This page is for MSA Search, version 2.2.0.
> For other versions, use one of these documentation indexes:
> - 2.6.0 (Latest) (default): https://docs.nvidia.com/nim/bionemo/msa-search/2.6.0/llms.txt
> - 2.5.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.5.0/llms.txt
> - 2.4.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.4.0/llms.txt
> - 2.3.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.3.0/llms.txt
> - 2.2.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.2.0/llms.txt
> - 2.1.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.1.0/llms.txt
> - 2.0.0: https://docs.nvidia.com/nim/bionemo/msa-search/2.0.0/llms.txt
> - 1.0.0: https://docs.nvidia.com/nim/bionemo/msa-search/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/bionemo/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/bionemo/_mcp/server.

# 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:

```bash
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:
  ```json
  "SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR"
  ```

- `databases` (list[string], optional): Database names to search against. All databases are searched by default. **Database names are case-insensitive**; the response preserves the case you specify. Default: `["all"]`.

  **Important**: For ColabFold search type, the first database in the list is used for profile generation. When using `["all"]`, uniref30 is automatically placed first.

  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. The first database is used for profile generation.
  - `"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. 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. Default: `500`. **Note**: When GPU Server is enabled (default in version 2.0.0), this parameter must be set globally using 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"]`

## Paired Multiple Sequence Alignment Search

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

Request type: `POST`

Paired MSA search finds homologous sequences for each chain of a protein complex and pairs them by species, preserving co-evolutionary signals across chains. This is essential for accurate structure prediction of protein complexes.

### Input Parameters

- `sequences` (list[string] or dict[string, string], **required**): Protein sequences, one per chain. Must contain at least 2 sequences. Each sequence must be composed of the 20 standard amino acids (ARNDCQEGHILKMFPSTWYV). Can be provided as a list (chain IDs assigned automatically as identifiers such as "A" and "B") or as a dictionary keyed by chain ID.

  Examples:
  ```json
  ["VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH", "MHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPYTQRFFESFGDLST"]
  ```
  ```json
  {"A": "VLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSH", "B": "MHLTPEEKSAVTALWGKVNVDEVGGEALGRLLVVYPYTQRFFESFGDLST"}
  ```

- `databases` (list[string], optional): Databases to search against. Only databases with taxonomy information can be used for paired search. **Database names are case-insensitive**; the response preserves the case you specify. Default: `["all"]`.

  Examples: `["all"]`, `["uniref30_2302"]`

- `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`.

- `max_msa_sequences` (int, optional): Maximum sequences taken from the MSA per chain (only applies when `unpack=True`; when `unpack=False`, row count may exceed `NIM_GLOBAL_MAX_MSA_DEPTH` due to MMseqs2 internal pipeline behavior where prefilter limits are per-step, not strict global caps). Default: `500`. **Note**: When GPU Server is enabled (default since version 2.0.0), this parameter must be set globally using the `NIM_GLOBAL_MAX_MSA_DEPTH` environment variable at container startup.

- `pairing_strategy` (string, optional): Pairing strategy for cross-chain sequence matching. Default: `"greedy"`.

  Options:
  - `"greedy"`: Maximizes rows by including species with partial chain coverage, pairing all chains that have hits and leaving gaps in others.
  - `"complete"`: Only includes species where all chains have hits, producing fewer rows but with full coverage.

<Note>
For 2-chain searches, both strategies produce identical results. Differences only arise for 3+ chains.
</Note>

- `unpack` (boolean, optional): Controls output format. Default: `True`.

  - `True`: Returns N alignments (one per chain) keyed by chain ID (for example, "A", "B"), each **strictly limited** to `max_msa_sequences` rows.
  - `False`: Returns raw MMseqs2 output as a single "all_chains" alignment with chains concatenated using null-byte separators. Row count may exceed `NIM_GLOBAL_MAX_MSA_DEPTH` due to MMseqs2 internal pipeline behavior (prefilter limits are per-step, not strict global caps).

### Outputs

- `alignments_by_chain` (Dictionary[string → Dictionary[string → Dictionary[string → AlignmentFileRecord]]]): Paired MSA alignments organized by chain ID. When `unpack=True`, structure is `{chain_id: {database_name: {format: AlignmentFileRecord}}}`. When `unpack=False`, contains a single "all_chains" key with the concatenated paired alignment.

  Example response (with `unpack=True`):
  ```json
  {
    "alignments_by_chain": {
      "A": {
        "uniref30_2302": {
          "a3m": {
            "alignment": ">A|-|A\nVLSPADKTNVKAAWGKV...\n>UniRef100_UPI00148F070C...\nVLSPAD...",
            "format": "a3m"
          }
        }
      },
      "B": {
        "uniref30_2302": {
          "a3m": {
            "alignment": ">B|-|B\nMHLTPEEKSAVTALWGKV...\n>UniRef100_UPI0008DEA318...\nMHLTPE...",
            "format": "a3m"
          }
        }
      }
    },
    "metrics": {}
  }
  ```

  To access the A3M-formatted alignment for chain A from the uniref30_2302 database:
  ```python
  alignments_by_chain["A"]["uniref30_2302"]["a3m"]["alignment"]
  ```

- `metrics` (dictionary, optional): Contains information about the response useful for debugging and measuring performance. May be empty or null.

<Note>
The output format for paired MSA search is always A3M.
</Note>

## Structural Template Search

Endpoint path: `/biology/colabfold/msa-search/structure-templates/predict`

Request type: `POST`

Structural template search finds homologous protein structures by searching PDB-based databases and retrieves the corresponding mmCIF structure files. This endpoint combines MSA generation with template discovery in a single request, providing all inputs needed for template-based structure prediction.

### Input Parameters

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

  Example:
  ```json
  "SGSMKTAISLPDETFDRVSRRASELGMSRSEFFTKAAQR"
  ```

- `structural_template_databases` (list[string], optional): List of databases to search for structural templates. **Database names are case-insensitive**; the response preserves the case you specify. Default: value of `NIM_MSA_API_DEFAULT_STRUCTURAL_TEMPLATE_DBS` environment variable (typically `["pdb70_220313"]`).

  Examples: `["pdb70_220313"]`, `["pdb70_220313", "pdb100_230517"]`

- `msa_databases` (list[string], optional): Database names to search for MSA generation. The first database is used for profile generation, which determines template search results. **Database names are case-insensitive**; the response preserves the case you specify. Default: `["all"]`.

  Examples: `["all"]`, `["uniref30_2302"]`

- `e_value` (float, optional): The e-value threshold for filtering hits. Range: 0.0-1.0. Default: `0.0001`.

- `max_structures` (int, optional): Maximum number of PDB structures to return from template search. Default: `20`.

- `max_msa_sequences` (int, optional): Maximum sequences used for profile generation and MSA output. Default: `500`.

### Outputs

The response includes the same fields as the standard MSA search endpoint, plus template-specific outputs:

- `alignments`: MSA alignments organized by database and format (same as standard MSA search)

- `search_hits` (Dictionary[string → Dictionary[string → SearchHitRecord]]): Structural template hits organized by database. Each entry contains template hits in M8 (BLAST tabular) format.

  Each `SearchHitRecord` contains:
  - `hits` (string): Template hits with columns: query, target, fident, alnlen, mismatch, gapopen, qstart, qend, tstart, tend, evalue, bits, cigar. The output format can be customized via the `NIM_MMSEQS_CONVERTALIS_FORMAT` environment variable.
  - `format` (string): Always `"m8"`.

- `structures` (Dictionary[string → StructuralTemplate]): Retrieved PDB structures for template hits, organized by PDB ID.

  Each `StructuralTemplate` contains:
  - `structure` (string): The mmCIF file content
  - `format` (string): Always `"mmcif"`

- `metrics` (dictionary, optional): Performance and debugging information

Example response:
```json
{
  "alignments": {
    "uniref30_2302": {
      "a3m": {
        "alignment": ">query\nMVPSAGQLALF...",
        "format": "a3m"
      }
    },
    "colabfold": {
      "a3m": {
        "alignment": ">query\nMVPSAGQLALF...",
        "format": "a3m"
      }
    }
  },
  "search_hits": {
    "pdb70_220313": {
      "m8": {
        "hits": "query\t1abc_A\t85.0\t150\t...",
        "format": "m8"
      }
    }
  },
  "structures": {
    "1abc": {
      "structure": "data_1ABC\n_entry.id 1ABC\n...",
      "format": "mmcif"
    }
  },
  "metrics": {}
}
```

<Note>
Template search uses the ColabFold cascaded search approach internally. The profile generated from the first MSA database (e.g., uniref30_2302) is used to find structural templates.
</Note>

## Get Database Configuration

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

Request type: `GET`

<Warning>
**Deprecated**: This endpoint is deprecated in favor of `/v1/metadata` and will be removed in MSA 3.0. Use the `/v1/metadata` endpoint to retrieve information about available databases and model profiles.
</Warning>

### 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.
</Note>

## 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.