> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biohub.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch a predicted structure

> Download a legacy ESM Metagenomic Atlas structure by MGnify accession, matching the esmatlas.com API.

This endpoint keeps parity with the legacy esmatlas.com API, `https://api.esmatlas.com/fetchPredictedStructure/{id}`, for existing users of that API.
It serves the same ESMFold structures from the original ESM Metagenomic Atlas, which covers only the older MGnify protein database version that Atlas was built from.
Proteins are identified by their MGnify accession, such as `MGYP000166900001`, not by the `protein_hash` that the other Atlas endpoints use.

> [!NOTE]
>
> This endpoint does not cover proteins added to MGnify after that version, and it does not return data from the current ESM Atlas.
> For current Atlas proteins, structures, and features, use [Get Protein](https://docs.biohub.ai/api/protein/atlas/proteins/get.md).

> [!NOTE]
>
> Unlike the other Atlas endpoints, this endpoint requires a Biohub API key.
> [Create an API key](https://biohub.ai/developer-console/api-keys) and send it as a Bearer token in the `Authorization` header.

## Choose a format

Add a lowercase suffix to the structure ID to choose the file format.
Any other suffix, including `.PDB`, returns `400`.

| Suffix | Response | Content type |
| - | - | - |
| None or `.pdb` | Archived PDB file | `chemical/x-pdb` |
| `.cif` | CIF converted from the PDB file | `chemical/x-cif` |

The PDB file stores pLDDT on a 0 to 1 scale in the B-factor column.
The CIF file reports pLDDT on a 0 to 100 scale.
The response body is the raw file, not JSON, so save it to disk as the examples do.

```bash PDB theme={null}
curl --fail-with-body \
  -H "Authorization: Bearer $BIOHUB_API_KEY" \
  -o MGYP000166900001.pdb \
  "https://biohub.ai/api/data/esm-atlas/v1/fetchPredictedStructure/MGYP000166900001"
```

```bash CIF theme={null}
curl --fail-with-body \
  -H "Authorization: Bearer $BIOHUB_API_KEY" \
  -o MGYP000166900001.cif \
  "https://biohub.ai/api/data/esm-atlas/v1/fetchPredictedStructure/MGYP000166900001.cif"
```

```python Python theme={null}
import os

import requests

structure_id = "MGYP000166900001"
response = requests.get(
    f"https://biohub.ai/api/data/esm-atlas/v1/fetchPredictedStructure/{structure_id}",
    headers={"Authorization": f"Bearer {os.environ['BIOHUB_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
with open(f"{structure_id}.pdb", "wb") as f:
    f.write(response.content)
```

```text PDB theme={null}
HEADER                                            01-FEB-23
TITLE     ESMFOLD V1 PREDICTION FOR MGYP000166900001
...
ATOM      1  N   MET A   1       2.861   4.850  26.782  1.00  0.97           N
ATOM      2  CA  MET A   1       1.832   5.831  26.449  1.00  0.98           C
ATOM      3  C   MET A   1       2.285   6.726  25.300  1.00  0.98           C
...
```

```text CIF theme={null}
loop_
_ma_qa_metric_local.label_asym_id
_ma_qa_metric_local.label_comp_id
_ma_qa_metric_local.label_seq_id
_ma_qa_metric_local.metric_id
_ma_qa_metric_local.metric_value
_ma_qa_metric_local.model_id
_ma_qa_metric_local.ordinal_id
A ILE 2 2 94.75 1 2
A ALA 3 2 98.42857142857143 1 3
...
ATOM 1 N N MET A 1 1 2.861 4.850 26.782 1.00 97.0 1
ATOM 2 C CA MET A 1 1 1.832 5.831 26.449 1.00 98.0 1
...
```

```json 401 theme={null}
{
  "error": "Unauthorized. Provide a valid API key via Authorization: Bearer <key>",
  "request_id": "51ab8198-42f4-4567-b6fe-3369046d45d4"
}
```

```json 404 theme={null}
{
  "detail": "Predicted structure not found for MGYP999999999999."
}
```

## CIF output

> [!WARNING]
>
> The `.cif` response reproduces the esmatlas.com conversion, including its known issues:
>
> * It has no `data_` block header.
> * It averages each residue's pLDDT without that residue's first atom, except for the first residue.
> * It shifts each residue's pLDDT to the following residue and drops the last residue's pLDDT.
> * It prints pLDDT values with floating-point noise, such as `57.99999999999999`.
> * It hardcodes chain, entity, and model identifiers.
>
> If you need standards-compliant mmCIF, download the PDB file and convert it with a validating tool such as [Gemmi](https://gemmi.readthedocs.io/).


## OpenAPI

````yaml openapi/esm-atlas-structures-openapi.json GET /api/data/esm-atlas/v1/fetchPredictedStructure/{structure_id}
openapi: 3.1.0
info:
  title: ESM Atlas Structures API
  description: >-
    Legacy-parity endpoint for the esmatlas.com fetchPredictedStructure API.
    Covers only the older MGnify protein database version that the original ESM
    Metagenomic Atlas was built from.
  version: 1.0.0
servers:
  - url: https://biohub.ai
security:
  - HTTPBearer: []
paths:
  /api/data/esm-atlas/v1/fetchPredictedStructure/{structure_id}:
    get:
      tags:
        - Proteins
      summary: Fetch a predicted structure
      description: >-
        Download the ESMFold-predicted structure for an MGnify protein from the
        original ESM Metagenomic Atlas, matching the legacy esmatlas.com API.
        Covers only the older MGnify database version that Atlas was built from,
        not current ESM Atlas data. Returns the archived PDB file, or a CIF
        conversion when the ID ends in `.cif`.
      operationId: fetch_predicted_structure
      parameters:
        - name: structure_id
          in: path
          required: true
          description: >-
            MGnify protein accession, `MGYP` followed by exactly 12 digits. Add
            lowercase `.pdb` or no suffix for PDB, or `.cif` for CIF.
          schema:
            type: string
            pattern: ^MGYP[0-9]{12}(\.pdb|\.cif)?$
      responses:
        '200':
          description: >-
            The predicted structure file. `Content-Disposition` names the file
            `{id}.pdb` or `{id}.cif`.
          content:
            chemical/x-pdb:
              schema:
                type: string
                description: PDB file with pLDDT on a 0 to 1 scale in the B-factor column.
              example: >
                HEADER                                            01-FEB-23

                TITLE     ESMFOLD V1 PREDICTION FOR MGYP000166900001

                ...

                ATOM      1  N   MET A   1       2.861   4.850  26.782  1.00 
                0.97           N  

                ATOM      2  CA  MET A   1       1.832   5.831  26.449  1.00 
                0.98           C  

                ATOM      3  C   MET A   1       2.285   6.726  25.300  1.00 
                0.98           C  
            chemical/x-cif:
              schema:
                type: string
                description: >-
                  CIF conversion of the archived PDB file, with pLDDT on a 0 to
                  100 scale.
              example: |
                loop_
                _ma_qa_metric.id
                _ma_qa_metric.mode
                _ma_qa_metric.name
                1 global pLDDT
                2 local  pLDDT
                #
                loop_
                _ma_qa_metric_local.label_asym_id
                _ma_qa_metric_local.label_comp_id
                _ma_qa_metric_local.label_seq_id
                _ma_qa_metric_local.metric_id
                _ma_qa_metric_local.metric_value
                _ma_qa_metric_local.model_id
                _ma_qa_metric_local.ordinal_id
                A ILE 2 2 94.75 1 2
                A ALA 3 2 98.42857142857143 1 3
                A PHE 4 2 98.75 1 4
                #
                loop_
                _atom_site.group_PDB
                _atom_site.id
                _atom_site.type_symbol
                _atom_site.label_atom_id
                _atom_site.label_comp_id
                _atom_site.label_asym_id
                _atom_site.label_entity_id
                _atom_site.label_seq_id
                _atom_site.Cartn_x
                _atom_site.Cartn_y
                _atom_site.Cartn_z
                _atom_site.occupancy
                _atom_site.B_iso_or_equiv
                _atom_site.pdbx_PDB_model_num

                ATOM 1 N N MET A 1 1 2.861 4.850 26.782 1.00 97.0 1
                ATOM 2 C CA MET A 1 1 1.832 5.831 26.449 1.00 98.0 1
                ATOM 3 C C MET A 1 1 2.285 6.726 25.300 1.00 98.0 1
                #
        '400':
          description: >-
            Unsupported output format, such as `.xyz` or `.PDB`. An unsupported
            suffix is reported before an invalid ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
              example:
                detail: Output format '.xyz' is not supported.
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              example:
                error: >-
                  Unauthorized. Provide a valid API key via Authorization:
                  Bearer <key>
                request_id: 51ab8198-42f4-4567-b6fe-3369046d45d4
        '404':
          description: No predicted structure exists for this ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
              example:
                detail: Predicted structure not found for MGYP999999999999.
        '422':
          description: >-
            Malformed structure ID. A non-MGYP ID returns a string `detail`. An
            ID with disallowed characters or more than 128 characters returns a
            list-shaped `detail`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Detail'
              examples:
                not_mgyp:
                  summary: ID is not MGYP plus 12 digits
                  value:
                    detail: >-
                      Structure ID must be MGYP followed by exactly 12 ASCII
                      digits.
                invalid_characters:
                  summary: ID has disallowed characters
                  value:
                    detail:
                      - type: string_pattern_mismatch
                        loc:
                          - path
                          - structure_id
                        msg: >-
                          String should match pattern
                          '^[A-Za-z0-9][A-Za-z0-9_.-]*$'
                        input: MGYP$invalid
                        ctx:
                          pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]*$
        '503':
          description: >-
            The structure archive or authentication is temporarily unavailable.
            The body shape depends on which component failed, so key on the
            status code. Retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                archive_unavailable:
                  summary: Archive read failed
                  value:
                    detail: The ESM Atlas archive is temporarily unavailable.
                service_unreachable:
                  summary: Archive service unreachable
                  value:
                    status: error
                    message: The ESM Atlas archive service is temporarily unavailable.
                    request_id: 51ab8198-42f4-4567-b6fe-3369046d45d4
                auth_unavailable:
                  summary: Authentication unavailable
                  value:
                    error: Authentication is temporarily unavailable. Please retry.
                    request_id: 51ab8198-42f4-4567-b6fe-3369046d45d4
        '504':
          description: >-
            The structure archive did not respond within 30 seconds. Retry
            later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              example:
                status: error
                message: The ESM Atlas archive request timed out.
                request_id: 51ab8198-42f4-4567-b6fe-3369046d45d4
components:
  schemas:
    Detail:
      type: object
      title: Detail
      properties:
        detail:
          description: Explanation of the error.
          anyOf:
            - type: string
            - type: array
              items:
                type: object
      required:
        - detail
    Unauthorized:
      type: object
      title: Unauthorized
      properties:
        error:
          type: string
        request_id:
          type: string
      required:
        - error
        - request_id
    ServiceError:
      type: object
      title: ServiceError
      properties:
        status:
          type: string
        message:
          type: string
        detail:
          type: string
        request_id:
          type: string
        error:
          type: string
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: Biohub API key from https://biohub.ai/developer-console/api-keys.

````

## Related topics

- [ESM Atlas](https://docs.biohub.ai/learn/guides/esm-atlas.md)
- [Atlas API guides](https://docs.biohub.ai/learn/tutorials/atlas/overview.md)
- [Join SAE features and structures](https://docs.biohub.ai/learn/guides/esm-atlas-extract-sae-folds-join.md)
- [Biohub MCP structure viewer](https://docs.biohub.ai/biohub-mcp/structure-viewer.md)
- [Biohub MCP server](https://docs.biohub.ai/biohub-mcp/overview.md)
