← API reference
Sequence analysis

IgBLAST API

Annotate antibody and T cell receptor sequences against germline V, D and J genes.

IgBLAST is NCBI's aligner for immunoglobulin and T cell receptor variable domains. It reports the top germline V, D, J and constant-region matches for each query, the rearrangement summary (chain type, stop codons, V-J frame, productivity), the V-D and D-J junction details with their N/P nucleotides, and the framework and complementarity determining regions under either the IMGT or the Kabat delineation. Nucleotide queries run through igblastn and protein queries through igblastp; a nucleotide run also writes the AIRR Rearrangement TSV and, on request, a clonotype summary of the whole repertoire.

Web form Documentation ↗ Input parameters ↗ Examples ↗ Home page ↗ Paper ↗ Source code ↗ License ↗
Submit POST /api/igblast/

Queues a run and returns 202 with the job.

Schema GET /api/igblast/

Returns this tool's metadata and the fields below, as JSON.

Runtime

The NCBI IgBLAST distribution and its prebuilt AIRR-C human, AIRR-C mouse, NCBI mouse, rhesus monkey and human constant-region germline databases are installed by setup_system.sh. Runs on CPU; no GPU is used. · Executable · Moderate (s)

License

Permissive. Public domain: a US Government work from NCBI, with no copyright asserted and no restriction on commercial use. The IMGT-derived and AIRR-C/OGRDB germline sets carry their own attribution terms.

Input method

Set input_mode to choose how inputs are supplied. Only fields for the selected method are used.

Example presets

Send {"preset": "human_igh_airr"} to load an example and its bundled inputs. Add other request fields to override its settings. The schema includes all presets under tool.presets.

presetDescription
human_igh_airrY14934, the human rearranged heavy chain NCBI's own IgBLAST web service names as its example accession, against the AIRR-C human germline set and the NCBI human constant-region genes. Leaves the AIRR rearrangement table alongside the flat query-anchored report. Source ↗
human_rf_repertoireFive rheumatoid factor heavy chains from the same GenBank submission as the example accession (Y14934-Y14938), annotated together so the run also writes a clonotype summary: the IgG1 pair share a V(D)J assignment and differ only in CDR3, which is what puts them in clonotypes of their own. Source ↗
mouse_igh_reportThe mouse igblastn example from the IgBLAST cookbook -- NCBI's mouse_gl_V, mouse_gl_D and mouse_gl_J with the mouse auxiliary file, -show_translation and -outfmt 3 -- run against X67210, a BALB/c hybridoma IgG2b heavy chain mRNA that carries its constant region as well as the rearranged V(D)J. Source ↗
mouse_vh_proteinThe igblastp example from the IgBLAST cookbook -- mouse_gl_V, -organism mouse, -outfmt 3 -- on the V domain of the same X67210 heavy chain. A protein query aligns against germline V genes only, so there is no D, J, junction or AIRR table for it. Source ↗
Request body

Fields

The same names the web form posts. See the field type table for what each kind means over HTTP.

Name Type Required Default Description
job_name string text no igblast-demo Job name Names the files this run leaves: <job name>.airr.tsv, <job name>.igblast.txt and <job name>.clonotypes.txt. up to 80 characters.
sequence_type string select no nucleotide Query type igblastn aligns a rearranged nucleotide sequence against V, D and J germline genes and can also call the constant region. igblastp aligns a translated V domain against germline V genes only: D, J, C, the junction and the AIRR table do not apply to it. In this form: One field chooses the program, because IgBLAST ships the two as separate executables. One of: nucleotide, protein.
input_fasta string textarea yes >Y14934.1 Homo sapiens mRNA for IgG1 rheumatoid factor immunoglobulin heavy chain GGGGGAGG … Query sequence or FASTA One bare sequence (line wrapping allowed) or FASTA records with unique headers; every record is annotated independently. Nucleotide queries accept A, C, G, T, U and the IUPAC ambiguity letters; protein queries accept the amino-acid letters. Up to 5000 records and 400,000 characters per run. In this form: IgBLAST's -query takes a file; what you enter here is written to query.fasta inside the isolated run directory. A designed sequence from an earlier ProteinMPNN, LigandMPNN, AbMPNN or AntiFold run can be dropped in whole from the picker above; those write amino acids, so set the query type to protein. up to 400000 characters.
inputs_file string file no — Query file Upload a FASTA file, or a plain-text sequence. The file's text is sent to the compute node and used exactly as if it had been typed above. file types .fasta,.fa,.fna,.faa,.fas,.seq,.txt.
organism string select no human Organism IgBLAST's -organism. Chooses the internal annotation data that places the framework and CDR boundaries, so it has to match the germline databases below. Ig is supported for human, mouse, rat, rabbit and rhesus monkey; TCR only for human and mouse. One of: human, mouse, rat, rabbit, rhesus_monkey.
ig_seqtype string select no Ig Receptor type IgBLAST's -ig_seqtype. TCR needs TCR germline databases, which NCBI does not distribute prebuilt: build them from IMGT with bin/edit_imgt_file.pl and bin/makeblastdb, and point IGBLAST_GERMLINE_ROOT at them. One of: Ig, TCR.
germline_db_v string select no auto Germline V database IgBLAST's -germline_db_V. Automatic picks NCBI's recommended prebuilt set for the organism above: the AIRR-C set for human, NCBI's own set for mouse and rhesus monkey. Any BLAST database installed under the germline root can be chosen instead. One of: auto, airr_c_129S1_SvImJ.V, airr_c_AKR_J.V, airr_c_A_J.V, airr_c_BALB_c_ByJ.V, airr_c_C3H_HeJ.V, airr_c_C57BL_6.V, airr_c_C57BL_6J.V, airr_c_CAST_EiJ.V, airr_c_CBA_J.V, airr_c_DBA_1J.V, airr_c_DBA_2J.V, airr_c_LEWES_EiJ.V, airr_c_MRL_MpJ.V, airr_c_MSM_MsJI.V, airr_c_NOD_ShiLtJ.V, airr_c_NOR_LtJ.V, airr_c_NZB_BlNJ.V, airr_c_PWD_PhJ.V, airr_c_SJL_J.V, airr_c_balbc.V, airr_c_human_ig.V, mouse_gl_V, rhesus_monkey_V.
germline_db_d string select no auto Germline D database IgBLAST's -germline_db_D, for nucleotide queries only. Light-chain and TCR alpha/gamma rearrangements have no D segment and IgBLAST simply reports none, so leaving this on Automatic is safe for a mixed repertoire. One of: auto, (empty), airr_c_human_igh.D, mouse_gl_D.
germline_db_j string select no auto Germline J database IgBLAST's -germline_db_J, for nucleotide queries only. The auxiliary coding-frame file is keyed to the J genes, so the CDR3 end and FWR4 are only annotated when the two agree. One of: auto, (empty), airr_c_human_ig.J, mouse_gl_J, rhesus_monkey_J.
c_region_db string select no auto Constant region database IgBLAST's -c_region_db, for nucleotide queries only. Identifies the isotype when the query runs into the constant region. NCBI distributes a prebuilt set for human only, so Automatic leaves it unset for every other organism. In this form: A query that stops at the end of the J segment, as most V(D)J amplicons do, has no constant region to call and reports an empty c_call. One of: auto, (empty), ncbi_human_c_genes.
domain_system string select no imgt Domain delineation IgBLAST's -domain_system: which numbering convention the framework and complementarity determining regions are cut at. One of: imgt, kabat.
show_translation boolean checkbox no true Show translated alignments IgBLAST's -show_translation. Prints the amino-acid translation above the nucleotide alignment in the readable report. Nucleotide queries only.
extend_align5end boolean checkbox no false Extend V alignment at the 5' end IgBLAST's -extend_align5end. Forces the V alignment out to the start of the query, which recovers the first framework residues of a read beginning inside FR1.
extend_align3end boolean checkbox no false Extend J alignment at the 3' end IgBLAST's -extend_align3end. Forces the J alignment out to the end of the query.
min_v_length number number no 9 Minimum V length IgBLAST's -min_V_length: shorter V alignments are not reported. Default 9. minimum 9, maximum 1000.
min_j_length number number no 0 Minimum J length IgBLAST's -min_J_length: shorter J alignments are not reported. Default 0, meaning no minimum. Nucleotide queries only. minimum 0, maximum 1000.
min_d_match number number no 5 Minimum D match IgBLAST's -min_D_match: the consecutive nucleotide bases a D gene must match to be called. Raise it to suppress the spurious short D hits a hypermutated junction attracts. Nucleotide queries only. minimum 5, maximum 100.
v_penalty number number no -1 V mismatch penalty IgBLAST's -V_penalty. Default -1, which tolerates the somatic hypermutation a matured V segment carries. minimum -3, maximum -1.
d_penalty number number no -2 D mismatch penalty IgBLAST's -D_penalty. Default -2. Nucleotide queries only. minimum -4, maximum -1.
j_penalty number number no -2 J mismatch penalty IgBLAST's -J_penalty. Default -2. Nucleotide queries only. minimum -3, maximum -1.
allow_vdj_overlap boolean checkbox no false Allow V(D)J genes to overlap IgBLAST's -allow_vdj_overlap. Active only when the D and J mismatch penalties are set to -4 and -3; a run that asks for it without them is refused rather than silently ignoring the option.
write_airr boolean checkbox no true Write the AIRR rearrangement table Runs IgBLAST with -outfmt 19 and keeps the result as <job name>.airr.tsv: one row per query with the V, D, J and C calls, the junction, every FWR and CDR, and the per-segment alignment coordinates, under the AIRR Rearrangement schema. This is the file offered at the top of the results page. Nucleotide queries only.
report_format string select no 3 Readable report format IgBLAST's -outfmt for the readable report kept as <job name>.igblast.txt. Format 3 is IgBLAST's own default and the one its documented examples use. One of: 3, 4, 7, (empty).
num_alignments_v number number no 3 V alignments to report IgBLAST's -num_alignments_V: germline V genes shown per query in the readable report. Default 3. minimum 0, maximum 100.
num_alignments_d number number no 3 D alignments to report IgBLAST's -num_alignments_D. Default 3. Nucleotide queries only. minimum 0, maximum 100.
num_alignments_j number number no 3 J alignments to report IgBLAST's -num_alignments_J. Default 3. Nucleotide queries only. minimum 0, maximum 100.
num_alignments_c number number no 2 C alignments to report IgBLAST's -num_alignments_C. Default 2. Only used when a constant region database is selected. minimum 0, maximum 100.
num_clonotype number number no 100 Top clonotypes to report IgBLAST's -num_clonotype, written to <job name>.clonotypes.txt through -clonotype_out. A clonotype groups the queries sharing their V(D)J calls, productivity and CDR3. Set to 0 to skip the clonotype pass. Nucleotide queries only. minimum 0, maximum 100000.
evalue string text no — E-value threshold IgBLAST's -evalue. Leave empty for the program's own default: 20 for igblastn, 1 for igblastp. up to 32 characters.
word_size string text no — Word size IgBLAST's -word_size, the length of the best perfect match the word finder seeds on. Leave empty for the program's default; the minimum is 4 for nucleotide queries and 2 for protein. up to 8 characters.
gapopen string text no — Gap open cost IgBLAST's -gapopen. Leave empty for the program's default. up to 8 characters.
gapextend string text no — Gap extend cost IgBLAST's -gapextend. Leave empty for the program's default. up to 8 characters.
strand string select no both Query strand IgBLAST's -strand. Default both, which is what lets IgBLAST report a reverse-complemented read and set rev_comp in the AIRR table. Nucleotide queries only. One of: both, plus, minus.
num_threads number number no 4 Threads IgBLAST's -num_threads. Default 4. minimum 1, maximum 32.
Example

A request that runs

These are the defaults, exactly as the web form would post them.

curl -X POST https://athanortools.com/api/igblast/ \
  -H 'Content-Type: application/json' \
  -d '{
  "input_mode": "text",
  "job_name": "igblast-demo",
  "sequence_type": "nucleotide",
  "input_fasta": ">Y14934.1 Homo sapiens mRNA for IgG1 rheumatoid factor immunoglobulin heavy chain\nGGGGGAGGCCTGGTCAAGCCTGGGGGGTCCCTGAGACTCTCCTGTGCAGCCTCTGGATTCCCCTTCAGTA\nACTACACCATGCACTGGGTCCGCCAGGCTCCAGGGAAGGGGCTGGAGTGGGTCTCATCCATTACTAGTAG\nTAGTAGTTACAGATATTACGCAGACTCAGTGGAGGGCCGATTCACCATCTCCAGAGACAACGCCAAGAAC\nTCACTGTATCTGCAAATGAACAGCCTGAGAGCCGAGGACACGGCTGTGTATTTCTGTGTGAGAGATCGGG\nGCTATGATAGTAGTGGTTATTACGGAAATCTTGACTGCTGGGGCCAGGGAACCCTGGTCACCGTCTCCTC\nA\n",
  "organism": "human",
  "ig_seqtype": "Ig",
  "germline_db_v": "auto",
  "germline_db_d": "auto",
  "germline_db_j": "auto",
  "c_region_db": "auto",
  "domain_system": "imgt",
  "show_translation": true,
  "extend_align5end": false,
  "extend_align3end": false,
  "min_v_length": 9,
  "min_j_length": 0,
  "min_d_match": 5,
  "v_penalty": -1,
  "d_penalty": -2,
  "j_penalty": -2,
  "allow_vdj_overlap": false,
  "write_airr": true,
  "report_format": "3",
  "num_alignments_v": 3,
  "num_alignments_d": 3,
  "num_alignments_j": 3,
  "num_alignments_c": 2,
  "num_clonotype": 100,
  "evalue": "",
  "word_size": "",
  "gapopen": "",
  "gapextend": "",
  "strand": "both",
  "num_threads": 4
}'

The reply is 202 with a queued job; poll its status_url until status is succeeded or failed. See the quick start for the whole exchange.

Responses

What comes back

statusMeaning
queued Accepted, waiting for the jobs ahead of it. `position` counts how many those are.
running The tool is executing now.
succeeded Finished; `result` holds the tool's output and `license` the terms it came under.
failed Finished; `error` holds a code and a message.
cancelled Abandoned at the submitter's request; there is no result. A job cancelled before its turn never ran at all.

Errors

codeMeaning
invalid_input The client supplied invalid or incomplete input.
tool_unavailable The requested third-party dependency is not available on this host.
execution_failed A configured third-party tool exited unsuccessfully.
internal_error An adapter failed in a way it does not describe. The detail is in the server log, not the response.
not_found No job has that id. Finished jobs are dropped eventually.