---
title: "(ESM3, ESMC) Decodes tokens sequence, structure, or function annotations"
method: POST
path: "/api/v1/decode"
tags: ["v1"]
---

# (ESM3, ESMC) Decodes tokens sequence, structure, or function annotations

`POST /api/v1/decode`

## Request

- Base URL: `https://dev.evolutionaryscale.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://dev.evolutionaryscale.ai/api/v1/decode`
- Auth: HTTP bearer

## Headers

- `accept` string, nullable

## Request body

- DecodeRequest
  - `model` 'esm3-open-2024-03' | 'esmc-300m-2024-12' | 'esmc-600m-2024-12' | 'esmc-6b-2024-12', required: You may have access to additional, private models as well. These will be visible on the Rate Limits page under the Developer Console
  - `potential_sequence_of_concern` boolean: Disclose potential sequences of concern. For approved users, such sequences will not go through additional safety filtering. Reach out if you are interested in using this.
  - `inputs` Tokens, required
    - `sequence` integer[], nullable: Sequence as a list of tokens as integers.
    - `coordinates` array[], nullable: Coordinates of the N, CA, C atom sequence as a Nx37x3 array.
      - array[]
        - number[]
    - `structure` integer[], nullable: Structure output from the model as a list of integer tokens.
    - `secondary_structure` integer[], nullable: Secondary structure in 8-class DSSP format.
    - `sasa` integer[], nullable: Solvent accessible surface area (SASA) as a list of integers.
    - `function` array[], nullable: Function annotations, as a list of integers.
      - integer[]
    - `residue_annotation` array[], nullable: Residue annotations tokens, as a list of integers.
      - integer[]

## Response `200`

Successful Response

- DecodeResponse
  - `model` 'esm3-open-2024-03' | 'esmc-300m-2024-12' | 'esmc-600m-2024-12' | 'esmc-6b-2024-12', required: You may have access to additional, private models as well. These will be visible on the Rate Limits page under the Developer Console
  - `created` string, required: ISO formatted date time
  - `potential_sequence_of_concern` boolean: Indicate that the returned sequence may be of potential concerns.
  - `warning_messages` string[], nullable: Warning messages returned by FastAPI.
  - `outputs` Tracks, required
    - `sequence` string, nullable: Sequence of amino acids. As input, this can be partially masked out with `_` or the literal `<mask>`, for example to get logprob over masked positions
    - `secondary_structure` string, nullable: Secondary structure in 8-class DSSP format. Masked positions may be given as `_` or as the literal `<pad>`.
    - `sasa` union[], nullable: Solvent accessible surface area (SASA) as a list of floats. A position may also be a SASA vocab token: <pad>, <motif>, <unk>, <0-0.8>, <0.8-4.0>, <4.0-9.6>, <9.6-16.4>, <16.4-24.5>, <24.5-32.9>, <32.9-42.0>, <42.0-51.5>, <51.5-61.2>, <61.2-70.9>, <70.9-81.6>, <81.6-93.3>, <93.3-107.2>, <107.2-125.4>, <125.4-151.4>, <151.4-inf>. Nones are replaced with padding. 03/18/2025: A bug was fixed where 'inf' prior to this date was returned encoded as '-1', it will instead be 1000 going forward
      - union
        - integer
        - number
        - '<pad>' | '<motif>' | '<unk>' | '<0-0.8>' | '<0.8-4.0>' | '<4.0-9.6>' | '<9.6-16.4>' | '<16.4-24.5>' | '<24.5-32.9>' | '<32.9-42.0>' | '<42.0-51.5>' | '<51.5-61.2>' | '<61.2-70.9>' | '<70.9-81.6>' | '<81.6-93.3>' | '<93.3-107.2>' | '<107.2-125.4>' | '<125.4-151.4>' | '<151.4-inf>'
    - `function` array[], nullable: Function annotations, as a list of 3-tuples: (interpro tag, start, end). Start and end are 1-indexed, inclusive. We support interpro tags from version 95.0.
      - unknown[]
        - unknown
    - `coordinates` array[], nullable: Coordinates of the N, CA, C atom sequence as a Nx37x3 array.
      - array[]
        - number[]
    - `plddt` number[], nullable: Per position plddt predictions for a protein. Usually produced by structure decoder.
    - `ptm` number, nullable: Predicted TM score of a protein. Usually produced by structure decoder.
    - `crmsd` number, nullable: Constrained RMSD between the generated protein coordinates and the input protein coordinates. Produced by the generate endpoint.
    - `globularity` number, nullable: Globularity of the generated protein. Produced by the generate endpoint.
    - `interface` string[], nullable: Annotations on residues that participate in a multimer interface.
    - `interface_ptm` number, nullable: Interface TM score of a protein.
    - `pae` array[], nullable: Predicted Aligned Error matrix for the protein. Shape is L x L. Values are rounded to 2 decimals (well within 0.5 A bin width)
      - number[]

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-23** `cfa834c15600`: 2 info
  - added the new optional `header` request parameter `accept`
  - added the media type `application/vnd.evolutionaryscale.pickle` for the response with the status `200`
- **2026-09-01** `556ff7afc275`: 1 breaking
  - response property `outputs/sasa/anyOf[subschema #1]/items/` list-of-types was widened by adding types `string` to media type `application/json` of response `200`

[Operation history](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api/changes/api/v1/decode/post.md)

---

[API](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api.md) - [All operations](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evolutionaryscale/apis/evolutionaryscale-api/revisions/28a490b11fe1?raw)