> This page is for MSA Search, version 1.0.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 the [complete OpenAPI Specification for the MSA Search NIM here](https://docs.api.nvidia.com/nim/reference/colabfold-msa-search).

## Predict a Multiple Sequence Alignment Search

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

Request type: `post`

### Input parameters

- `sequence (string)`: Required. An input string representing a protein sequence and composed of valid IUPAC amino acid single-letter codes.

- `databases (list[strings])`: Optional (default: all available databases). Number of tokens to be generated.

- `e_value (float)`: Optional. Sequences with an e-value less than this are not included in the MSA.

- `iterations (int)`: Optional. The number of search iterations. Running more iterations produces more sensitive results.

- `output_alignment_formats (list[strings])`: A list of output alignment formats, which can contain any of `a3m` or `fasta`.

- `max_msa_sequences (int)`: Optional. The maximum number of sequences included in the output MSA of each database. **Note**: This parameter is overridden by the `NIM_GLOBAL_MAX_MSA_SEQUENCES` environment variable and the limit to the number of NIM sequences is 10,000.


### Outputs

- `alignments (Dictionary[string -> Dictionary[string, Alignment Record]])`: This structure holds a dictionary, with keys corresponding to each search database. The values corresponding to the dictionary name keys are dictionaries mapping from the file format to an output Alignment Record. Each Alignment Record contains the raw alignment data and a format field. The following is an example of accessing the fast-formatted alignment for the Uniref30_2302 database:

### Example

<Tabs>
<Tab title="Curl">

```bash
#!/bin/bash

# Define protein sequence
SEQUENCE="MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN"

# Create JSON payload
JSON='{
"sequence": "'"$SEQUENCE"'",
"e_value": 0.0001,
"iterations": 1,
"databases": ["Uniref30_2302", "colabfold_envdb_202108", "PDB70_220313"],
"search_type": "alphafold2",
"output_alignment_formats": ["fasta", "a3m"],
"max_msa_sequences": 1000
}'

# Make request
echo "Making request..."
curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON" \
http://localhost:8000/biology/colabfold/msa-search/predict
```

</Tab>
<Tab title="Python">

```python
import requests
import json


if __name__ == "__main__":
    sequence = "MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN"  # Replace with your sequence value of interest
    headers = {
    "content-type": "application/json"
    }
    data = {
    "sequence": sequence,
    "e_value": 0.0001,
    "iterations": 1,
    "databases": ["Uniref30_2302", "colabfold_envdb_202108", "PDB70_220313"],
    "search_type": "alphafold2",
    "output_alignment_formats" : ["fasta", "a3m"],
    "max_msa_sequences" : 1000
    }
    print("Making request...")
    response = requests.post("http://localhost:8000/biology/colabfold/msa-search/predict",headers=headers, data=json.dumps(data))
    ## Get the fasta formatted record
    record = response.json()["alignments"]["Uniref30_2302"]["a3m"]
    print(record["format"]) ## prints "a3m"
    print(record["alignment"]) ## prints the full A3M-formatted alignment file, which may be very large.
```

</Tab>
</Tabs>


- `templates (dictionary)`: Always returned, but may be empty. This _would_ contain structural templates. This field is maintained for compatibility with the OpenFold NIM API.

- `metrics (dictionary)`: Always returned, but may be empty. This dictionary contains information about the response that may be useful for debugging and measuring performance.

## Get the configured databases

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

Request type: `get`

### Input parameters

None: This endpoint takes no inputs.

### Outputs

- `configs (dictionary)`: Always returned, except on error. This is a nested dictionary that contains information about all of the configured MSA databases. This can be converted to YAML to see the original configuration file.

### Example

<Tabs>
<Tab title="Curl">

```bash
#!/bin/bash

SEQUENCE="MALWMRLLPLLALLALWGPDPAAAFVNQHLCGSHLVEALYLVCGERGFFYTPKTRREAEDLQVGQVELGGGPGAGSLQPLALEGSLQKRGIVEQCCTSICSLYQLENYCN"

# Create JSON payload
JSON_DATA='{
"sequence": "'"$SEQUENCE"'",
"e_value": 0.0001,
"iterations": 1,
"databases": ["Uniref30_2302", "colabfold_envdb_202108", "PDB70_220313"],
"search_type": "alphafold2",
"output_alignment_formats": ["fasta", "a3m"],
"max_msa_sequences": 1000
}'

echo "Making request..."

# Make the POST request
# Note: This script requires jq to be installed for JSON processing
response=$(curl -s -X POST \
-H "Content-Type: application/json" \
-d "$JSON_DATA" \
http://localhost:8000/biology/colabfold/msa-search/predict)

# Extract and display the A3M format and alignment
# Using jq to parse the JSON response
echo "Format: $(echo $response | jq -r '.alignments.Uniref30_2302.a3m.format')"
echo "Alignment:"
echo "$response" | jq -r '.alignments.Uniref30_2302.a3m.alignment'
```

</Tab>
<Tab title="Python">

```python
import requests
import json


if __name__ == "__main__":
    headers = {
        "content-type": "application/json"
        }
    print("Making request...")
    response = requests.get("http://localhost:8000/biology/colabfold/msa-search/config/msa-database-configs",headers=headers)
    print(json.dumps(response.json(), indent=4))
```

</Tab>
</Tabs>


## Readiness check

Endpoint path: `/v1/health/ready`

### Input parameters

None.

### Outputs

The output of the endpoint is a JSON response with a value that indicates the readiness of the microservice. When the NIM is ready, it returns the response `200`.

### Example

<Tabs>
<Tab title="Curl">

```bash
#!/bin/bash
URL=${NIM_URL:-"http://localhost:8000/v1/health/ready"}
curl -s -w "\nStatus code: %{http_code}\n" -H "Content-Type: application/json" $URL
```

</Tab>
<Tab title="Python">

```python
import requests
import os

if __name__ == "__main__":
    url = os.environ.get("NIM_URL", "http://localhost:8000/v1/health/ready")
    headers = {
        "content-type": "application/json"
    }
    try:
        response = requests.get(url, headers=headers)
        print(f"NIM readiness check returned {response.status_code}")
        assert response.status_code == 200, f"Unexpected status code: {response.status_code}"
    except Exception as e:
        print(f"Health query failed: {e}")
```

</Tab>
</Tabs>