---
title: "Design a set of sequencing barcodes"
method: POST
path: "/barcode_design"
tags: ["Primers & oligos"]
---

# Design a set of sequencing barcodes

`POST /barcode_design`

## Request

- Base URL: `https://seqbench.com/api/v1`
- URL: `https://seqbench.com/api/v1/barcode_design`
- Auth: none required

Build a set of DNA barcodes that are pairwise at least a chosen edit distance apart, so a read error cannot turn one barcode in the pool into another. Honours a GC window, a homopolymer cap and excluded motifs (the restriction sites you clone with) during the search rather than filtering afterwards, and can extend a set you already have rather than replacing it. Reports the distance ACHIEVED — re-derived over the finished pool, not assumed from the search — plus how many read errors that distance lets you correct and detect. Deterministic given a seed. Returns fewer barcodes than asked, with a reason, when the constraints leave no room.

## Request body

- object
  - `count` integer: How many barcodes to design (max 1000). A plate is 96 or 384.
  - `length` integer: Barcode length in bases (default 12). Longer barcodes make a given distance far easier to reach.
  - `minDistance` integer: Minimum edit distance between any two barcodes (default 3). Distance 3 corrects one read error and detects two; distance 5 corrects two. Distance 1 only means 'not identical' and corrects nothing.
  - `metric` 'levenshtein' | 'hamming': 'levenshtein' counts substitutions, insertions and deletions — the right choice for nanopore or PacBio, and the safe default. 'hamming' counts substitutions only, which is faster and adequate when the platform's errors are substitutions (Illumina), but gives NO protection against an indel shifting one barcode into another.
  - `gcMin` number: Lowest GC% a barcode may have.
  - `gcMax` number: Highest GC% a barcode may have.
  - `maxHomopolymer` integer: Longest run of one base allowed (default 3). Homopolymers miscall on every platform and are the one composition rule worth keeping tight.
  - `exclude` string[]: Motifs no barcode may contain, checked on both strands — the restriction sites you clone with. Literal ACGT only.
  - `existing` string[]: Barcodes you already use. They are held fixed and the new ones are kept distant from them, so a second plate does not collide with the first.
  - `seed` integer: Seeds the search. Change it for a different set from the same constraints; keep it to reproduce one.

## Response `200`

Tool ran successfully.

- SuccessResponse: Standard success envelope returned by every single-tool call.
  - `ok` unknown, required
  - `tool` string, required: The tool slug that ran.
  - `result` object, required: Tool-specific output object. Its shape depends on the tool — call `GET /{tool}` or see the docs for each tool's fields.
  - `gate` GateResult
    - `pass` boolean, required: True if and only if every hard check passed.
    - `checks` GateCheck[], required
      - `id` string, required
      - `label` string, required
      - `severity` 'hard' | 'soft', required
      - `pass` boolean, required
      - `message` string, required
      - `value` number
      - `threshold` string
    - `notChecked` string[], required: Honest list of what this gate does NOT verify.
  - `provenance` Provenance, required
    - `apiVersion` string, required
    - `tool` union, required: Tool slug, or an array of slugs (one per step) for a workflow.
      - string
      - string[]
    - `generatedAt` string, date-time, required: ISO 8601 timestamp of when the result was generated.

## Other responses

- `400`: Invalid argument or the tool could not run.
- `404`: Unknown tool.
- `429`: Rate limited (metered tools only). Body carries code `rate_limited` and retryable `true`; honor the Retry-After header.
- `503`: A metered tool is momentarily at capacity. The identical request should succeed after Retry-After; body carries code `upstream_unavailable`.

---

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