> This page is for Developer Documentation.

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

# Get Fieldset by ID

GET https://{tenant_name}.benchling.com/api/v3/fieldset/{fieldset_id}

Get a single Fieldset by ID.

Reference: https://docs.benchling.com/docs/api/benchling-api/fieldset/get

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `fieldset_id` (string, required) — ID of the Fieldset.

### Query parameters

- `returning` (string, optional) — Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
- `omit` (string, optional) — Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.

## Response

### 200

OK

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable) — Reason the Fieldset was archived
- `archived` (boolean, optional) — If the Fieldset is archived
- `availableRegistrationNamingOptions` (list of enum, optional) — The registration naming strategies available for entities of implementing schemas. Determines how entities are named when registered.
  - Allowed values: `NEW_IDS`, `IDS_FROM_NAMES`, `DELETE_NAMES`, `SET_FROM_NAME_PARTS`, `REPLACE_NAMES_FROM_PARTS`, `KEEP_NAMES`, `REPLACE_ID_AND_NAME_FROM_PARTS`
- `constraint` (Constraint, optional, nullable) — Uniqueness constraint configuration for registered entities of schemas that implement this fieldset. Ensures that a specified combination of field values is unique across those entities. Null means no constraint.
- `createdAt` (string, optional) — DateTime the Fieldset was created
- `description` (string, optional) — The description of this Fieldset.
- `displayName` (string, optional) — The user-facing name of this fieldset.
- `fieldDefinitions` (string, optional) — The field definitions that all schemas implementing this fieldset are required to include.
- `id` (string, optional)
- `itemIdPrefix` (string, optional, nullable) — Prefix string prepended to generated entity IDs. Setting this on a fieldset replaces the entity ID prefix on all implementing schemas.
- `itemType` (enum, optional, nullable) — The entity item type that schemas implementing this Fieldset contain (e.g. DNA_SEQUENCE, AA_SEQUENCE, MIXTURE). Null when the Fieldset declares no base bioentity type.
  - Allowed values: `AA_SEQUENCE`, `ANTIBODY`, `CUSTOM_ENTITY`, `DNA_OLIGO`, `DNA_SEQUENCE`, `ENTRY`, `EQUIPMENT`, `MIXTURE`, `MOLECULE`, `OLIGO_CONJUGATE`, `OLIGO_DUPLEX`, `RNA_OLIGO`, `RNA_SEQUENCE`, `TRIAL_SUBJECT`
- `modifiedAt` (string, optional) — DateTime the Fieldset was last modified
- `nameTemplate` (EntityNameTemplate, optional, nullable) — Entity name template that auto-generates names for entities of implementing schemas when they are registered. Used in conjunction with `availableRegistrationNamingOptions`. Null means no template.
- `organization` (OrganizationRef, optional) — Organization the Fieldset is in
- `systemName` (string, optional) — The machine-readable identifier for warehouse and API access.

## Errors

### 400 Fieldset Get Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Fieldset Get Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Fieldset Get Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Fieldset Get Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Fieldset Get Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### Constraint

Defines uniqueness requirements for entities within a schema. Constraints ensure that registered entities have unique values across specified fields (see `fieldDefinitionNames`) or unique domain-specific properties (see `TypeSpecificConstraint`). The hasUniqueResidues field is a legacy indicator for sequence uniqueness.

- `__typename` (string, optional)
- `fieldDefinitionNames` (list of string, optional, nullable)
- `hasUniqueResidues` (boolean, optional, nullable)

### EntityNameTemplate

A name template for entities.

- `__typename` (string, optional)
- `parts` (list of EntityNameTemplatePart, optional)
- `shouldOrderPartsBySequence` (boolean, optional)

### OrganizationRef

- `__typename` (string, optional)
- `id` (string, optional)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### EntityNameTemplatePart

A part in an entity name template.

- `__typename` (string, optional)
- `configuration` (EntityNameTemplatePartConfiguration, optional, nullable) — Union of TextNameTemplatePartConfiguration, FieldNameTemplatePartConfiguration, ProteinChainNameTemplatePartConfiguration, ProteinDomainNameTemplatePartConfiguration
- `type` (enum, optional)
  - Allowed values: `CHILD_ENTITY_LOT_NUMBER`, `COMPLEX_POLYMER_COMPONENT`, `CREATED_AT_DATE`, `CREATED_AT_YEAR`, `FIELD`, `HOISTED_FIELD`, `LINKED_BIOENTITY_REGISTRY_IDENTIFIER`, `PROJECT`, `PROTEIN_CHAIN`, `PROTEIN_DOMAIN`, `REGISTRY_IDENTIFIER_NUMBER`, `REGISTRY_IDENTIFIER_NUMBER_BASE_26`, `SALT_CODES`, `SEPARATOR`, `TEXT`

### EntityNameTemplatePartConfiguration

### TextNameTemplatePartConfiguration

Configuration for a literal text name template part.

- `__typename` (string, optional)
- `text` (string, optional)

### FieldNameTemplatePartConfiguration

Configuration for a schema field name template part.

- `__typename` (string, optional)
- `field` (SchemaFieldDefinitionRef, optional)

### ProteinChainNameTemplatePartConfiguration

Configuration for a protein chain name template part.

- `__typename` (string, optional)
- `proteinChain` (ProteinFormatChain, optional) — A chain in a protein format, representing the slot where a polypeptide chain can be used in an entity of this format. Chains are uniquely identified by their label in the format. Chains can have multiplicity, meaning there are multiple physical instances of the same chain in a protein of this format.

### ProteinDomainNameTemplatePartConfiguration

Configuration for a protein domain name template part.

- `__typename` (string, optional)
- `proteinDomain` (ProteinFormatDomain, optional) — A domain in a protein format, representing the slot where an amino acid sequence can be used in an entity of this format. Domains are uniquely identified by their label in the format.

### SchemaFieldDefinitionRef

- `__typename` (string, optional)
- `id` (string, optional)

### ProteinFormatChain

A chain in a protein format, representing the slot where a polypeptide chain can be used in an entity of this format. Chains are uniquely identified by their label in the format. Chains can have multiplicity, meaning there are multiple physical instances of the same chain in a protein of this format.

- `__typename` (string, optional)
- `chainPositions` (list of ProteinFormatChainPosition, optional) — A list of all the chain positions of this chain in the format.
- `domains` (list of ProteinFormatDomain, optional) — The domains that compose this chain.
- `label` (string, optional) — A human-readable label for the chain, such as 'Heavy' or 'Light 1'. Chains are labeled with an index only when multiple distinct chains of the same type exist. These labels are unique among distinct chains in a format.
- `type` (enum, optional) — The type of the chain.
  - Allowed values: `HEAVY`, `LIGHT`, `NONE`, `ALPHA`, `BETA`, `JOINING`

### ProteinFormatDomain

A domain in a protein format, representing the slot where an amino acid sequence can be used in an entity of this format. Domains are uniquely identified by their label in the format.

- `__typename` (string, optional)
- `domainPositions` (list of ProteinFormatDomainPosition, optional) — A list of all the domain positions of this domain in the format.
- `label` (string, optional) — A human-readable label for the domain, uniquely identifying the domain within the format.
- `optional` (boolean, optional) — Whether this domain is optional in the format. If true, entities of this format may not have this domain.
- `type` (enum, optional) — The type of the domain (e.g., VH, VL, CH1).
  - Allowed values: `VL`, `CL`, `VH`, `VHH`, `CH1`, `CH2`, `CH3`, `CH4`, `J`, `H`, `L`, `VA`, `CA`, `VB`, `CB`, `VG`, `CG`, `VD`, `CD`, `F`, `ELEMENT`

### ProteinFormatChainPosition

Defines each instance of a polypeptide chain within a `ProteinFormat`, specifying the chain type and its constituent domains. Each chain position has a unique ref identifier and lists the domain positions (see `ProteinFormatDomainPosition`) that compose it in order from N-terminus to C-terminus. For example, a heavy chain position might reference domain positions [VH, CH1, Hinge, CH2, CH3].

- `__typename` (string, optional)
- `domainPositions` (list of ProteinFormatDomainPosition, optional) — A list of all the domain positions that make up the chain position, in order
- `ref` (integer, optional) — A unique identifier for a physical component (chain or domain) in a protein format. This is used to form a HELM reference that is used in the protein's complex polymer structure.
- `type` (enum, optional) — Type of the chain.
  - Allowed values: `HEAVY`, `LIGHT`, `NONE`, `ALPHA`, `BETA`, `JOINING`

### ProteinFormatDomainPosition

Defines a domain position within a `ProteinFormat`, specifying the domain type and identity of each physical domain in the protein format. Each domain position has a unique ref identifier used to construct HELM notation for complex polymer structures. Domain positions are grouped into ProteinFormatDomains, and each group can be uniquely identified by its label, and will be a single amino acid sequence entity in proteins of this format.

- `__typename` (string, optional)
- `optional` (boolean, optional) — Whether this domain is optional in the format. If true, entities of this format may not have this domain.
- `ref` (integer, optional) — A unique identifier for a physical component (chain or domain) in a protein format. This is used to form a HELM reference that is used in the protein's complex polymer structure.
- `type` (enum, optional) — Type of the domain
  - Allowed values: `VL`, `CL`, `VH`, `VHH`, `CH1`, `CH2`, `CH3`, `CH4`, `J`, `H`, `L`, `VA`, `CA`, `VB`, `CB`, `VG`, `CG`, `VD`, `CD`, `F`, `ELEMENT`

## Examples

**Response**

```json
{
  "__typename": "__typename",
  "archiveReason": "archiveReason",
  "archived": true,
  "availableRegistrationNamingOptions": [
    "NEW_IDS"
  ],
  "constraint": {
    "__typename": "__typename",
    "fieldDefinitionNames": [
      "fieldDefinitionNames"
    ],
    "hasUniqueResidues": true
  },
  "createdAt": "createdAt",
  "description": "description",
  "displayName": "displayName",
  "fieldDefinitions": "fieldDefinitions",
  "id": "id",
  "itemIdPrefix": "itemIdPrefix",
  "itemType": "AA_SEQUENCE",
  "modifiedAt": "modifiedAt",
  "nameTemplate": {
    "__typename": "__typename",
    "parts": [
      {}
    ],
    "shouldOrderPartsBySequence": true
  },
  "organization": {
    "__typename": "__typename",
    "id": "id"
  },
  "systemName": "systemName"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/fieldset/fieldset_id"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/fieldset/fieldset_id';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```