SnapGene Server Request API

September 12, 2026 02:29
Updated

SnapGene Server is no longer available for purchase or use by commercial third parties. This guide is provided for existing SnapGene Server users.

A list of currently supported commands, their parameters and a description of the command.

Common Parameters

Several commands use a common set of names to specify parameters:

See Enzyme Set Names.

See Reading Frame Names.

General Commands

Request Server Status

Requests status information for the server. Can be used to "ping" the server and make sure it is still operational. This request doesn't actually change any the server status information (lastRequest, requestCount).

Input Parameters
request	“status"

Output Parameters
response	“status"
serverVersion	Version number of the serverver
requestCount	Number of requests to the server (this request does not count)
lastRequest	Time of the last request (this request does not count)
uptime	Time the server has been running
license	State of the current license (if it is found, valid, expiration, etc.)
licenseExpiration	Date of the license expiration (YY-MM-DD)

Errors
0	Success

Report File Information

Input Parameters
request	“reportFileInfo"
inputFile	full path to input .dna file

Output Parameters
response	“reportFileInfo"
code	error code
sequenceLength	length of the sequence in base pairs
sequenceTopology	either “circular” or “linear"
serverIndex	index of server daemon that ran the report

Error Codes
0	Success
1	Unable to open input .dna file or it isn’t a DNA file

File Conversion

Import DNA File

Converts a file from a different DNA format to snapgene native .dna.

Input Parameters
request	“importDNAFile"
inputFile	full path to file to import
outputFile	Full path to .dna file to write to disk
enzymeSet	Enzyme set to save to this file (see list of possible names below)
minORFLen	Minimum detection length for ORFs to save to this file. Default is 75.
readingFrames	Reading frame option to save with this file (see list of possible names below). Default is ORFS

Output Parameters
response	“importDNAFile"
code	Return code for the request

Error Codes
0	Success
1	Could not open input file
2	File type unsupported
4	Could not create output file
5	File stamping failure
6	Encoding failed
7	Sequence indexing failed
8	Recognition sequence indexing failed

Export DNA File

Converts a file from snapgene native .dna to another file format. The outputFile must contain the extension .gb[1] or .fasta to convert to that particular format. Otherwise the output format is ambiguous and will the request will fail.

Input Parameters
request	“exportDNAFile"
inputFile	full path to file to read
outputFile	Full path of file to write to disk
exportFilter	Type of filter to export. Currently supported export filters are listed below.

Output Parameters
response	“exportDNAFile"
code	Return code for the request

Error Codes
0	Success
1	Unable to open input file or the file is not a .dna file
2	Export filter unsupported
3	Internal exporting code failed

Feature Commands

Detect Features

Detects feature on a .dna file. Will only detect new features present in the input feature database.

To detect from multiple databases, call this command repeatedly. Input and output parameters can be the same to modify the file in place.

For each new feature added, an optional note is appended to the feature's /note field (as specified in the genbank file format. This can also be viewed in Snapgene Desktop in the /note field at the bottom of the edit features dialog box.

Input Parameters
request	“detectFeatures"
inputFile	Full path to .dna file to read
outputFile	Full path of .dna file to write to disk
featureDatabase	Full path to feature database file. This should use the .dna file format but often uses the extension .ftrs (either will work.

Output Parameters
response	“detectFeatures"
code	Return code for the request

Error Codes
0	Success
1	Unable to open input file
2	Unable to create output file
3	Feature database file does not exist

Report Features

Returns the list of all features in the inputFile.

Input Parameters
request	“reportFeatures"
inputFile	Full path to .dna file to read

Output Parameters
response	“reportFeatures"
features	Array of features
code	Return code for the request

Error Codes
0	Success
1	Unable to open input file

The feature object is of the following format:

Feature Objects
name	name of the feature
type	type of the feature (there are many--I don't have them all listed here)
rangebegin	beginning base pair of the entire feature
rangeEnd	ending base pair of the entire feature
direction	can be one of the following: nondirectional, forward-directional, reverse-directional, bidirectional
segments	array of segments, introns are not included.
attributes	object with many key/value pairs, they are not all listed here. Values are string arrays.

The segment object is of the following format:

Segment Objects
name	name of the segment
rangeBegin	beginning base pair of the segment
rangeEnd	ending base pair of the segment
color	color of the segment in #AAAAAAAA format
type	can be one of the following: standard, gap, run-on-translation

Generate SVG Map

Input Parameters
request	“generateSVGMap”
inputFile	full path to .dna file to generate map from
linear	true for linear map, false for circular map
showEnzymes	True to show enzymes on the map
showPrimers	True to show primers on the map
showFeatures	True to show features on the map
showORFs	True to display ORFs on the map
designSize	set the requested size of the map in width x height. The actual size might be different because the map generation code performs extra logic to ensure the text graphical elements are all visible
outputSvgDom	file to text fragment of the svg objects and tooltip DOM objects
outputSvgJSStatic	file to text fragment of the javascript code required for hover/selection (static part) the static part can be shared for all maps for the same version of snapgene server. NOTE: this parameter is deprecated --- there is no need to generate JS files using generateSVGMap. Instead use the JS file in /opt/gslbiotech/snapgene-server/examples/js/map-seq-interactivity.js
outputSvgJSDynamic	file to text fragment of the javascript code required for hover/selection (dynamic part). NOTE: this parameter is deprecated
outputSvgCss	file to text fragment of the css code required for proper rendering of the SVG DOM. NOTE: this parameter is deprecated
optimize	Removes extra SVG attributes that are not necessary for correctly rendering the SVG.
dataModel	User defined attribute used to identify a particular map or sequence view. Useful when supporting multiple maps or sequences on the same page
dataId	User defined attribute used to identify a particular map or sequence view. Useful when supporting multiple maps or sequences on the same page.
title	Defines the title to use for the map. If the title is not defined or set to an empty string, then the default title (the filename without the extenion) is used. To clear the title completely from display, set the value to one space, e.g. “ “.
subtitle	Defines the subtitle to use for the map. If the subtitle is not defined or set to an empty string, then the default title (the number of base pairs) is used. To clear the title completely from display, set the value to one space, e.g. “ “.
addMouseEvents	Adds mouse handlers in the hittest region of the DOM. Default is true.
enzymeSet	Override enzyme set to use saved with the .dna file
minORFLen	Override the minimum ORF length saved with the .dna file
readingFrame	Override the reading frame saved with the .dna file

Output Parameters
response	"generateSVGMap"
code	Return code for the request

Errors
0	Success
1	Update to open input for or it isn't a DNA file
2	DNA file can be opened, requires updating, but couldn't be updated
4	Unable to write SVG file
5	Unable to write JS file
6	Unable to write CSS file
100	Internal Error

Generates a web based map in several text file fragments.

The DOM object returned from outputSvgDOM will contain attributes with data-sequence-length and data-topology.

NOTE: This method used to be called generateMapParts.

Generate PNG Map

Generates a similar map compared to generateSVGMap except the output is PNG instead of Dom, JS and css files.

Input Parameters
request	"generatePNGMap"
inputFile	full path to .dna file to generate map from
linear	true for linear map, false for circular map
showEnzymes	true to display enzymes
showFeatures	true to display features
showPrimers	true to display primers
showORFs	true to display ORFs
designSize	set the requested size of the map in width x height. The actual size might be different because the map generation code performs extra logic to ensure the text graphical elements are all visible
outputPng	Output PNG file
enzymeSet	Override enzyme set to use saved with the .dna file
minORFLen	Override the minimum ORF length saved with the .dna file
readingFrame	Override the reading frame saved with the .dna file

Output Parameters
response	“generatePNGMap"
code	error code for the request

Error Codes
0	Value 2
1	Update to open input for or it isn't a DNA file
2	DNA file can be opened, requires updating, but couldn't be updated
100	Internal error

Generate SVG Sequence

Input Parameters
request	generateSVGSequence
inputFile	full path to .dna file to generate a sequence from
showEnzymes	true to display enzymes
showFeatures	true to display features
showPrimers	true to display primers
showTranslation	true to display translations (this is currently unsupported)
outputSvgDom	file to text fragment of the svg objects
outputSvgJSStatic	file to text fragment of the javascript code required for hover/selection (static part) the static part can be shared for all maps for the same version of snapgene server.
outputSvgJSDynamic	file to text fragment of the javascript code required for hover/selection (dynamic part)
outputSvgCss	file to text fragment of the css code required for proper rendering of the SVG DOM
optimize	Removes extra SVG attributes that are not necessary for correctly rendering the SVG.

User defined attribute used to identify a particular map or sequence view. Useful when supporting multiple maps or sequences on the same page.

User Defined
dataID	User defined attribute used to identify a particular map or sequence view.
addMouseEvents	Adds mouse handlers in the hittest region of the DOM. Default is true.
enzymeSet	Override enzyme set to use saved with the .dna file
minORFLen	Override the minimum ORF length saved with the .dna file
readingFrame	Override the reading frame saved with the .dna file

Output Parameters
response	“generateSVGSequence"
code	Error code for

Error Codes
0	Success.
1	Update to open input for or it isn't a DNA file.
2	DNA file can be opened, requires updating, but couldn't be updated.
4	Unable to write SVG file.
5	Unable to write JS file.
6	Unable to write CSS file.
100	Internal Error.

Generates a web-based sequence in several fragments.

Import Primers from List

Input Parameters:
request	importPrimersFromList
inputFile	full path to input .dna file
inputPrimerFile	full path to json file with primers to import
outputDnaFile	full path to output .dna file with imported primers
requirePerfectMatch	Integer value. 0 means no perfect match required. -1 means a perfect match is required for the entire primer. A value between 12-25 means a perfect match is required for that many bases of the primer.
requireUniqueBindingSite	true/false. Require a unique binding site for the primer to be imported.

Output Parameters
response	“importPrimersFromlist"
code	Error

Error Codes:
0	Success.
1	Unable to open input dna file or it isn’t a DNA file.
2	DNA file can be opened, requires updating, but couldn’t be updated.
3	Unable to open primer file.
4	Unable to write output DNA file.
100	Internal error.

Reads a list of primers in a json document and inserts them into a dna file. A new dna file is written.

The primer json document is of the following format:

array of objects of members. Members are:

[Primer Item 1, Primer Item 2, ...]

Each primer Item is:

{
"Name":"<primer name>", 
"Sequence":"<primer sequence>",
 "Notes":"<primer notes>"
}

Report Primers

Input Parameters
request	“reportPrimers"
inputDNAFile	full path to input.

Output Parameters
response	“reportPrimers"
code	error code
primers	json array of primers (see schema below)

Error Codes:
0	Success
1	Unable to open input dna file or it isn’t a DNA file.
2	DNA file can be opened, requires updating, but couldn’t be updated.
100	Internal error.

Opens a .dna file and outputs a report in JSON for all primers saved to the .dna file.

JSON Schema for primers:

color-user friendly name of color for primer
length-length of sequence (this is always the same as property character length
molecularWeight-formated string with weight of the primer
name-name of the primer
notes-notes for the primer
percentGC-formated string with the percentage GC for the sequence
sequence-actual sequence string of the primer
sites-JSON array of binding sites
- bindingSiteStart: start of the binding site in BP
- bindingSiteEnd: ending of the binding site in BP
- meltingTemperature: degrees centigrade for melting
- strand: specified which side of the sequence the primer is attached to (“Top” or“Bottom”)

Example output with four primers. One of the primers has two binding sites:

{
"code": 0,
"primers": [
{
     "color": "Black",
     "length": 39,
     "molecularWeight": "12,107.9 Da",
     "name": "A206K.REV",
     "notes": "<html><body>For introducing the monomerizing A206K mutation</body></html>",
     "percentGC": "56% GC",
     "sequence": "GTTGGGGTCTTTGCTCAGCTTGGACTGGGTGCTCAGGTA",
     "sites": [
}, {
{
} ]
"bindingSiteEnd": 2593,
"bindingSiteStart": 2555,
"meltingTemperature": 71,
"strand": "Bottom"
"color": "Black",
"length": 39,
"molecularWeight": "11,868.7 Da",
"name": "A206K.FOR",
"notes": "<html><body>For introducing the monomerizing A206K mutation</body></html>",
"percentGC": "56% GC",
"sequence": "TACCTGAGCACCCAGTCCAAGCTGAGCAAAGACCCCAAC",
"sites": [
{
}, {
} ]
"bindingSiteEnd": 2593,
"bindingSiteStart": 2555,
"meltingTemperature": 71,
"strand": "Top"
"bindingSiteEnd": 2593,
"bindingSiteStart": 2555,
"meltingTemperature": 71,
"strand": "Top"
},
"response": "reportPrimers"
}

Report Enzymes

Report ORFs

Input Parameters
request	“reportEnzymes"
inputFile	full path to input .dna file.
enzymeSet	enzyme set to use (see list of possible names below). Otherwise enzyme set saved with file is used.

Output Parameters
response	“reportEnzymes"
code	Error code.
setName	Name of the enzyme set.
count	Number of enzymes in library.
enzymes	json array of enzymes (see schema below).

Error Codes
0	Success.
1	Unable to open input dna file or it isn’t a DNA file.

For each JSON object in the enzymes JSON array:
id:	Unique identifier for the enzyme. This should match with the map or sequence.
name:	Name of the enzyme.
Hits:	JSON array of hit objects (locations the enzyme cuts the sequence.
Each hit object contains the following:
topCutPosition:	Top location of the enzyme cut (this is the typical value displayed).
bottomCutPosition:	If the cut is not blunt, then the bottom base position will be offset from the top.
methylationSensitive:	true or false.
blocked:	true or false.

Report ORFs

Input Parameters
request	“reportORFs"
inputFile	full path to input .dna fi

Ouput Parameters
response	“reportORFs"
code	error code
ORFs	jsonArray of ORF objects.

Error Codes:
0	Success
1	Unable to open input dna file or it isn’t a DNA file.

Response fields for each ORF:
fullRangeBegin:	First codon of ORF.
fullRangeEnd:	Last codon of ORF.
hitsStopCodon:	True if fullRangeEnd is the last codon. It is possible the plasmid ends before a stop codon is encountered.
lacksStartCodon:	In some configurations of ORF detection of a start codon is not required, if an ORF is detected without a start codon within the plasmid (i.e. the beginning of a linear map), this flag would be true.