Core endpoints
/pipeline POST for submitting predictions
Users can submit a prediction job by sending a POST method HTTP request to the pipeline endpoint https://api-nextgen-tools.iedb.org/api/v1/pipeline.
For example, here is a payload with 1 sequence, allele, and binding method to be submitted:
{ "pipeline_id": "",
"run_stage_range": [1,1],
"stages": [ { "stage_number": 1,
"tool_group": "mhci",
"input_sequence_text": ">LCMV Armstrong, Protein GP\nMGQIVTMFEALPHIIDEVINIVIIVLIVITGI",
"input_parameters": {
"alleles": "H2-Kb",
"peptide_length_range": [9,9],
"predictors": [ {
"type": "binding",
"method": "netmhcpan_el"
} ]
}
}
]
}
In order to submit with curl, some of the special characters may need to be escaped with backslashes (\):
curl -X POST "https://api-nextgen-tools.iedb.org/api/v1/pipeline" \
-H "accept: application/json" -H "Content-Type: application/json" \
-d "{ \"pipeline_id\": \"\", \"run_stage_range\": [1,1], \"stages\": [ { \"stage_number\": 1, \"tool_group\": \"mhci\", \"input_sequence_text\": \">LCMV Armstrong, Protein GP\nMGQIVTMFEALPHIIDEVINIVIIVLIVITGI\", \"input_parameters\": { \"alleles\": \"H2-Kb\", \"peptide_length_range\": [9,9], \"predictors\": [ { \"type\": \"binding\", \"method\": \"netmhcpan_el\" } ] } }]}"
The response will include the pipeline_id, results_id, URLs, warnings, and other key bits of information related to the request. If an error arises
that will prevent the job from running through, an errors item will be
returned. A typical response will look like:
{
"result_id": "1673373361.4166636-Xq9AyoYI",
"results_uri": "https://api-nextgen-tools.iedb.org/api/v1/results/1673373361.4166636-Xq9AyoYI",
"pipeline_id": "a1f2ab78-33b8-4a38-b484-d392bae43a39",
"pipeline_uri": "https://api-nextgen-tools.iedb.org/api/v1/pipeline/a1f2ab78-33b8-4a38-b484-d392bae43a39",
"pipeline_spec_id": "2c526066-1296-4fbd-9cc5-69005b55b026",
"pipeline_spec_uri": "https://api-nextgen-tools.iedb.org/api/v1/pipeline_spec/2c526066-1296-4fbd-9cc5-69005b55b026",
"warnings": [],
"input_sequence_text_id": "1673373361.4143195-nWkachZD",
"input_sequence_text_uri": "https://api-nextgen-tools.iedb.org/api/v1/get_object/1673373361.4143195-nWkachZD"
}
retrieve all possible parameters from each tool
Please visit these URLs to retrieve all possible parameters for each tool:
Usage examples
Some typical usage workflows are outlined in this section.
Single-stage T cell class I pipeline
Submit a single-stage pipeline request to run netmhcpan_el on 1 input sequence with 2 alleles and 2 lengths. This is the body of the POST request:
{
"pipeline_title": "My MHCI single-stage pipeline",
"email": "myaddress@somewhere.com",
"run_stage_range": [
1,
1
],
"stages": [
{
"stage_number": 1,
"tool_group": "mhci",
"input_sequence_text": ">LCMV Armstrong, Protein GP\nMGQIVTMFEALPHIIDEVINIVIIVLIVITGI",
"input_parameters": {
"alleles": "H2-Kb,H2-Db",
"peptide_length_range": [
9,
10
],
"predictors": [
{
"type": "binding",
"method": "netmhcpan_el"
}
]
}
}
]
}
The response will look similar to:
{
"result_id": "1650337009.595137-VIdw0wTm",
"results_uri": "https://api-nextgen-tools.iedb.org/api/v1/results/1650337009.595137-VIdw0wTm",
"pipeline_id": "ad99636f-3e72-49b3-a4d3-2c7fcc867457",
"pipeline_uri": "https://api-nextgen-tools.iedb.org/api/v1/pipeline/ad99636f-3e72-49b3-a4d3-2c7fcc867457",
"pipeline_spec_id": "765e8dbe-ef93-4a65-ad21-886f06a91b5a",
"pipeline_spec_uri": "https://api-nextgen-tools.iedb.org/api/v1/pipeline_spec/765e8dbe-ef93-4a65-ad21-886f06a91b5a",
"warnings": [],
"input_sequence_text_id": "471f6648-fe67-4e31-b4b0-f00d38da0e31",
"input_sequence_text_uri": "https://api-nextgen-tools.iedb.org/api/v1/get_object/471f6648-fe67-4e31-b4b0-f00d38da0e31"
}
Notes on the request and response
Including an
emailin the POST will result in messages being sent to the address as pipeline stages complete.Sending a GET to the
results_uriwill return the status of the pipeline. If the pipeline is complete, all results data will be returned as well.Sending a GET to the
pipeline_uriwill pull down the pipeline definition, including all stage information, input data, and table states.Sending a GET to the
pipeline_spec_uriwill pull down the pipeline definition without any input data and no linkage to results.
Single-stage cluster pipeline
Submit a single-stage pipeline request to run cluster on a set of peptide sequences. This is the body of the POST request:
{
"pipeline_id": "",
"run_stage_range": [
1,
1
],
"stages": [
{
"name": "Cluster",
"stage_number": 1,
"tool_group": "cluster",
"input_sequence_text": ">Mus Pep1\nLEQIHVLENSLVL\n>Mus Pep2\nFVEHIHVLENSLAFK\n>Mus Pep3\nGLYGREPDLSSDIKERFA\n>Mus Pep4\nEWFSILLASDKREKI\n>Mus Pep5\nDGFNTFTILKTDYDN\n>Mus Pep6\nNEKDGETFQLMGLY\n>Mus Pep7\nYGREPDLSLDIKEK\n>Mus Pep8\nLENSLVLKFHTVRDE\n>Mus Pep9\nAHLINEKDGETFQLM\n>Mus Pep10\nEEASSTGRNFNVQKINGEWHTIIL\n>Mus Pep11\nEKALVSSVRQRMKCS\n>Mus Pep12\nSRPFIFQEVIDLGGE\n>Mus Pep13\nNVEKINGEWHTIIL\n>Mus Pep14\nGIYYLNYDGFNTFTI\n>Mus Pep15\nDDVVASEALNSVWSGF\n>Mus Pep16\nGSMRVFVEHIHVLEN\n>Mus Pep17\nENIIDLTKTNRCLKA\n>Mus Pep18\nILGKLVKDYHLQFHR\n>Mus Pep19\nIGGPDDGVITPWQSSF\n>Mus Pep20\nDKETLSLEELKALLL\n>Mus Pep21\nLQSGFYSLSSLVTVP\n>Mus Pep22\nEELRRLAPITSDPTE\n>Mus Pep23\nTIFISLFLLSVCYSA\n>Rat Pep1\nASNKREKIEENGSMRVFMQH\n>Rat Pep2\nDIKEKFAKLCEAHGITRDNI\n>Rat Pep3\nEEASSTRGNLDVAKLNGDWF\n>Rat Pep4\nEENGSMRVFMQHIDVLENSL\n>Rat Pep5\nENSLGFKFRIKENGECRELY\n>Rat Pep6\nFMQHIDVLENSLGFKFRIKE\n>Rat Pep7\nFVEYDGGNTFTILKTDYDRY\n>Rat Pep8\nGDWFSIVVASNKREKIEENG\n>Rat Pep9\nGRTKDLSSDIKEKFAKLCEA\n>Rat Pep10\nKTPEDGEYFVEYDGGNTFTI\n>Rat Pep11\nLCEAHGITRDNIIDLTKTDR\n>Rat Pep12\nLINFKNGETFQLMVLYGRTK\n>Rat Pep13\nNLDVAKLNGDWFSIVVASNK\n>Rat Pep14\nRDNIIDLTKTDRCLQARG\n>Rat Pep15\nRELYLVAYKTPEDGEYFVEY\n>Rat Pep16\nRIKENGECRELYLVAYKTPE\n>Rat Pep17\nTFQLMVLYGRTKDLSSDIKE\n>Rat Pep18\nTFTILKTDYDRYVMFHLINF\n>Rat Pep19\nYDRYVMFHLINFKNGETFQL",
"input_parameters": {
"cluster_pct_identity": 0.7,
"peptide_length_range": [
0,
0
],
"predictors": [
{
"type": "cluster",
"method": "cliques"
}
]
}
}
]
}
Single-stage Pepmatch pipeline
Submit a single-stage pipeline request to run pepmatch on a set of peptide sequences. This is the body of the POST request:
{
"pipeline_id": "",
"run_stage_range": [
1,
1
],
"stages": [
{
"stage_number": 1,
"tool_group": "pepmatch",
"input_sequence_text": "DDEDSKQNIFHFLYR\nADPGPHLMGGGGRAK\nKAVELGVKLLHAFHT\nQLQNLGINPANIGLS\nHEVWFFGLQYVDSKG\nFVEHIHVLENSLAFK",
"input_parameters": {
"mismatch": 3,
"proteome": "Human",
"best_match": true
}
}
]
}
Single-stage PepX pipeline
Submit a single-stage pipeline request to run pepX on a set of peptide sequences. This is the body of the POST request:
{
"pipeline_id": "",
"run_stage_range": [
1,
1
],
"stages": [
{
"stage_number": 1,
"tool_group": "pepx",
"input_sequence_text": "FVQMMTAK\nMRYVASYL\nEDIISFIK\nYEVSQLKD\nYISEHEHF\nAEMYVAKF\nSEFEARVI\nIESIVHAF\nKYGPVFSF\nWERLAVLV\nHETTFNSI\nYVHMVTHF\nKYPENFFL\nPNLAFLRF\nTEFIFTTI\nHESLSHEL\nYERSIVDY\nIEKLFQSV\nTDGKVFQF\nTEFKFPQI\nHQKQISSL\nNQKRLTVY\nHQVVVAKY\nLQNSVKQY\nHSVLIHEY\nVSAVVHEY\nMQKEITAL\nSQAIIHQY\nTQQLMRVY",
"input_parameters": {
"qlevel": "gene",
"dataset_id": 2,
"datasource": "Abelin"
}
}
]
}
Single-stage pipeline with peptide input
Submit a netmhcpan_el prediction job for a set of peptides without breaking them
up into shorter sequences by setting the peptide_length_range to ‘null’.
{
"pipeline_id": "",
"run_stage_range": [
1,
1
],
"stages": [
{
"stage_number": 1,
"stage_type": "prediction",
"tool_group": "mhci",
"input_sequence_text": "MGQIVTMFE\nALPHIIDEVI\nNIVIIVLIVITGI",
"input_parameters": {
"alleles": "H2-Kb,H2-Db",
"peptide_length_range": null,
"predictors": [
{
"type": "binding",
"method": "netmhcpan_el"
}
]
}
}
]
}
Multi-stage pipeline with filters
Submit a request to first run netmhcpan_el, filter by percentile rank, and then pipe the results to the cluster tool (two-stage pipeline).
{
"pipeline_id": "07e433b9-b8da-49e9-887e-eec050223162",
"run_stage_range": [
1,
2
],
"stages": [
{
"stage_number": 1,
"tool_group": "mhci",
"input_sequence_text": ">LCMV Armstrong, Protein GP\nMGQIVTMFEALPHIIDEVINIVIIVLIVITGI",
"input_parameters": {
"alleles": "H2-Kb,H2-Db",
"peptide_length_range": [
9,
10
],
"predictors": [
{
"type": "binding",
"method": "netmhcpan_el"
}
]
},
"table_state": {
"columns": {
"binding.netmhcpan_el.percentile": {
"search": {
"min": "0",
"max": "20"
},
"tool_group": "mhci",
"source": "binding.netmhcpan_el",
"name": "percentile"
}
}
}
},
{
"stage_number": 2,
"tool_group": "cluster",
"piped_data": {
"piped_input": [
{
"piped_fields": [
"peptide_table.peptide"
],
"piped_stage_number": 1
}
]
},
"input_parameters": {
"cluster_pct_identity": "0.7",
"peptide_length_range": [
0,
0
],
"predictors": [
{
"type": "cluster",
"method": "cliques"
}
]
}
}
]
}
/pipeline GET for retrieving pipeline details
A GET request to the pipeline endpoint (https://api-nextgen-tools.iedb.org/api/v1/pipeline) will
return details about the submitted pipeline. For example:
curl -X GET "https://api-nextgen-tools.iedb.org/api/v1/pipeline/a2d8cae2-7d6f-4df9-87f5-3704462cd737" \
-H "accept: application/json"
Details returned include all pipeline configuration information, the various stages, input datasets, and filters. The response will look similar to:
{
"pipeline_id": "84e37db6-6404-4492-9a4d-75aef193e283",
"pipeline_title": "",
"pipeline_date": "2023-01-30",
"pipeline_spec_id": "d76d0287-e89e-4d13-917b-6d8dc92fd465",
"email": "",
"stages": [
{
"stage_id": "6871b1ae-6d9e-405a-80ca-668249cc427a",
"stage_url": "https://api-nextgen-tools.iedb.org/api/v1/stage/6871b1ae-6d9e-405a-80ca-668249cc427a",
"stage_number": 1,
"stage_type": "prediction",
"tool_group": "mhci",
"stage_display_name": "T Cell Prediction - Class I",
"stage_messages": {
"errors": [],
"warnings": []
},
"input_parameters": {
"alleles": "H2-Kb",
"predictors": [
{
"type": "binding",
"method": "netmhcpan_el"
}
],
"peptide_length_range": [
9,
9
]
},
"input_sequence_text": "IVLIVITGI",
"stage_result_id": "1675139470.684202-6YXGWKC1",
"stage_result_uri": "https://api-nextgen-tools.iedb.org/api/v1/results/1675139470.684202-6YXGWKC1",
"input_datasets": [
{}
],
"table_state": {}
}
]
}
/stage GET for retrieving stage information
A pipeline consists of one or more stages, with each stage corresponding to a prediction
with one of the available tools. Stage identifiers (stage_id) are returned by the
/pipeline GET endpoint. These identifiers
can be passed to the /stage endpoint (https://api-nextgen-tools.iedb.org/api/v1/stage) to retrieve details about the stage. For example:
curl -X GET "https://api-nextgen-tools.iedb.org/api/v1/stage/a1e0dd4d-897f-49e6-a005-adf915fda607" \
-H "accept: application/json"
Details returned include information specific to the requesting stage, including the source of the input, parameter selections, and links to the results. The output should look similar to:
{
"stage_id": "6871b1ae-6d9e-405a-80ca-668249cc427a",
"stage_type": "prediction",
"tool_group": "mhci",
"stage_display_name": "T Cell Prediction - Class I",
"stage_messages": {
"errors": [],
"warnings": []
},
"stage_status": "done",
"stage_result_id": "1675139470.684202-6YXGWKC1",
"stage_result_uri": "https://api-nextgen-tools.iedb.org/api/v1/results/1675139470.684202-6YXGWKC1",
"input_data": {
"input_parameters_id": "1675139470.6785612-fl0lKlEj",
"input_parameters_uri": "https://api-nextgen-tools.iedb.org/api/v1/get_object/1675139470.6785612-fl0lKlEj",
"input_sequence_text_id": "1675139470.682073-hXxjT9d1",
"input_sequence_text_uri": "https://api-nextgen-tools.iedb.org/api/v1/get_object/1675139470.682073-hXxjT9d1",
"input_datasets_id": "1675139470.6873922-PqK6zzj3",
"input_datasets_uri": "https://api-nextgen-tools.iedb.org/api/v1/get_object/1675139470.6873922-PqK6zzj3"
}
}
/results GET for retrieving stage results
A result_id from the /pipeline or /stage endpoint can be passed to the
/results endpoint (https://api-nextgen-tools.iedb.org/api/v1/results)
to retrieve status information and result data. For example:
curl -X GET "https://api-nextgen-tools.iedb.org/api/v1/results/1674108083.4757252-deM43fj1" -H "accept: application/json"
If the stage is still running, the output will look similar to:
{
"id": "1675138667.457741-YQAK34e8",
"type": "result",
"data": {
"results": [
{
"type": "input_sequence_table",
"table_columns": [
{
"name": "sequence_number",
"display_name": "seq #",
"type": "int",
"source": "core",
"sort_order": 0,
"row_sort_priority": 0,
"default_order": "ascending",
"description": "the index of sequence",
"hidden": false
},
{
"name": "sequence_name",
"display_name": "sequence name",
"type": "text",
"source": "core",
"sort_order": 0,
"row_sort_priority": null,
"default_order": null,
"description": "the name of sequence",
"hidden": false
},
{
"name": "sequence",
"display_name": "sequence",
"type": "text",
"source": "core",
"sort_order": 0,
"row_sort_priority": null,
"default_order": null,
"description": "sequence",
"hidden": false
}
],
"table_data": [
[
1,
"LCMV Armstrong, Protein GP",
"MGQIVTMFEALPHIIDEVINIVIIVLIVITGI"
]
]
}
],
"input_data": {
"alleles": "H2-Kb,H2-Db",
"predictors": [
{
"type": "binding",
"method": "netmhcpan_el"
}
],
"peptide_length_range": [
8,
14
]
},
"errors": [],
"warnings": []
},
"status": "pending"
}
If the stage has been completed, the status will be ‘done’ and the results
field will be populated, similar to:
{
"id": "1675139470.684202-6YXGWKC1",
"type": "result",
"data": {
"results": [
{
"type": "peptide_table",
"table_data": [
[
1,
"IVLIVITGI",
9,
1,
9,
"H2-Kb",
1,
"IVLIVITGI",
"IVLIVITGI",
"0.078096",
1.5
]
],
"table_columns": [
{
"name": "sequence_number",
"type": "int",
"hidden": false,
"source": "core",
"sort_order": 0,
"description": "the index of sequence",
"display_name": "seq #",
"default_order": null,
"row_sort_priority": null
},
{
"name": "peptide",
"type": "text",
"hidden": false,
"source": "core",
"sort_order": 3,
"description": "peptide sequence",
"display_name": "peptide",
"default_order": null,
"row_sort_priority": null
},
{
"name": "length",
"type": "int",
"hidden": false,
"source": "core",
"sort_order": 4,
"description": "The length of peptide",
"display_name": "peptide length",
"default_order": null,
"row_sort_priority": null
},
{
"name": "start",
"type": "int",
"hidden": false,
"source": "core",
"sort_order": 1,
"description": "The peptide's starting point from the sequence",
"display_name": "start",
"default_order": null,
"row_sort_priority": null
},
{
"name": "end",
"type": "int",
"hidden": false,
"source": "core",
"sort_order": 2,
"description": "The peptide's stop point from the sequence",
"display_name": "end",
"default_order": null,
"row_sort_priority": null
},
{
"name": "allele",
"type": "text",
"hidden": false,
"source": "core",
"sort_order": 5,
"description": "one of two, or more, forms of a given gene variant",
"display_name": "allele",
"default_order": null,
"row_sort_priority": null
},
{
"name": "peptide_index",
"type": "int",
"hidden": true,
"source": "core",
"sort_order": 6,
"description": "the index of peptide",
"display_name": "peptide index",
"default_order": null,
"row_sort_priority": null
},
{
"name": "core",
"type": "text",
"hidden": false,
"source": "binding.netmhcpan_el",
"sort_order": 3,
"description": "Always 9 amino acids long sequence. It's a construction used for sequence alignment and identification of binding anchors.",
"display_name": "netmhcpan_el core",
"default_order": null,
"row_sort_priority": null
},
{
"name": "icore",
"type": "text",
"hidden": false,
"source": "binding.netmhcpan_el",
"sort_order": 3,
"description": "Substring of peptide that encompasses all residues between P1 and P-omega of the MHC.",
"display_name": "netmhcpan_el icore",
"default_order": null,
"row_sort_priority": null
},
{
"name": "score",
"type": "float",
"hidden": false,
"source": "binding.netmhcpan_el",
"sort_order": 0,
"description": "binding prediction score which indicates binding affinity",
"display_name": "netmhcpan_el score",
"default_order": "descending",
"number_of_digits": 4,
"row_sort_priority": 0
},
{
"name": "percentile",
"type": "float",
"hidden": false,
"source": "binding.netmhcpan_el",
"sort_order": 1,
"description": "The percentile rank generated by comparing the peptide's IC50 against those of a set of random peptides from SWISSPROT database",
"display_name": "netmhcpan_el percentile",
"default_order": "ascending",
"number_of_digits": null,
"row_sort_priority": null
}
]
},
{
"type": "netmhcpan_allele_distance",
"table_data": [
[
"H2-Kb",
"H2-Kb",
"0.000"
]
],
"table_columns": [
{
"name": "input_allele",
"type": "text",
"hidden": false,
"source": "core",
"sort_order": 5,
"description": "the predicted allele",
"display_name": "Input Allele",
"default_order": null,
"row_sort_priority": null
},
{
"name": "closest_allele",
"type": "text",
"hidden": false,
"source": "core",
"sort_order": 5,
"description": " its nearest neighbor in the training set",
"display_name": "Closest Allele",
"default_order": null,
"row_sort_priority": null
},
{
"name": "allele_distances",
"type": "int",
"hidden": false,
"source": "core",
"sort_order": 6,
"description": " Alleles with lower distances to the training set will have more accurate predictions. A distance of 0 indicates a perfect match between alleles and values at or below 0.1 is considered acceptable for generating accurate predictions.",
"display_name": "Distance",
"default_order": null,
"row_sort_priority": null
}
]
},
{
"type": "input_sequence_table",
"table_columns": [
{
"name": "sequence_number",
"display_name": "seq #",
"type": "int",
"source": "core",
"sort_order": 0,
"row_sort_priority": 0,
"default_order": "ascending",
"description": "the index of sequence",
"hidden": false
},
{
"name": "sequence_name",
"display_name": "sequence name",
"type": "text",
"source": "core",
"sort_order": 0,
"row_sort_priority": null,
"default_order": null,
"description": "the name of sequence",
"hidden": false
},
{
"name": "sequence",
"display_name": "sequence",
"type": "text",
"source": "core",
"sort_order": 0,
"row_sort_priority": null,
"default_order": null,
"description": "sequence",
"hidden": false
}
],
"table_data": [
[
1,
"sequence 1",
"IVLIVITGI"
]
]
}
],
"warnings": [],
"input_data": {
"alleles": "H2-Kb",
"predictors": [
{
"type": "binding",
"method": "netmhcpan_el"
}
],
"peptide_length_range": [
9,
9
]
},
"errors": []
},
"status": "done"
}