VDJdb server REST API [BETA]

Accessing metadata

Information on database columns (such as their IDs, names and other metadata) can be obtaining by performing a GET request to https://vdjdb.cdr3.net/search/columns.

For example,

curl -X GET https://vdjdb.cdr3.net/search/columns

will return a JSON object with the following structure.

[
        ...
        {
                "name":"gene",
                "metadata" : {
                        "columnType": "txt",
                        "visible" : "1",
                        "searchable" : "1"
                        "dataType" : "factor",
                        "title": "Gene",
                        "comment" : "TCR chain: alpha or beta.",
                },
                "autocomplete" : true,
                "values" : [ "TRA" , "TRB" ]
        }
        ...
]

Searching the database

You can query the database by sending a POST request with a specific JSON content to https://vdjdb.cdr3.net/search.

The structure of JSON query is the following:

{
    "textFilters": [
        ...
    ],
    "sequenceFilters": [
        ...
    ]
}

Where the textFilters structure is

{
    "columnId": "(string)",     // Column name (any available column)
    "value": "(string)",        // Search value
    "filterType": "(string)",   // Filter type: exact, exact_set, pattern, substring_set, level
    "negative": (boolean)       // Return only results that do not match the filter
}

and the sequenceFilters structure is

{
    "columnId": "(string)",     // Column name (cdr3 or antigen.epitope)
    "query": "(string)",        // Search query
    "substitutions": (int),     // The number of substitutions
    "insertions": (int),        // The number of insertions
    "deletions": (int),         // The number of deletions
    "total": (int)              // Total number of mutations allowed
}

Sequence filters can only be applied to columns with "columnType": "seq" and will invoke a search and alignment procedure (more precisely, a sequence tree search). Text filters can be specified for any available column.

Note

Filters mirror the filtering functions implemented in VDJdb-standalone. Thus, parameter description can be found in the documentation of *Filter.groovy classes implemented for sequence and text columns respectively.

The structure of JSON response is the following:

[
        ...
        {
                "entries": [
                        ...
                        { "columnName": "gene", "value": "TRA" }
                        ...
                ]
        }
        ...
]

For example, the following request

curl -H "Content-Type: application/json" -X POST -d '{ "textFilters" : [{"columnId":"cdr3", "value":"CAAAASGGSYIPTF", "filterType":"exact", "negative":false }], "sequenceFilters" : [] }' https://vdjdb.cdr3.net/search

will produce

[{
"entries": [{
        "columnName": "complex.id",
        "value": "131"
}, {
        "columnName": "gene",
        "value": "TRA"
}, {
        "columnName": "cdr3",
        "value": "CAAAASGGSYIPTF"
}, {
        "columnName": "v.segm",
        "value": "TRAV1-2*01"
}, {
        "columnName": "j.segm",
        "value": "TRAJ6*01"
}, {
        "columnName": "species",
        "value": "HomoSapiens"
}, {
        "columnName": "mhc.a",
        "value": "HLA-B*35:01"
}, {
        "columnName": "mhc.b",
        "value": "B2M"
}, {
        "columnName": "mhc.class",
        "value": "MHCI"
}, {
        "columnName": "antigen.epitope",
        "value": "EPLPQGQLTAY"
}, {
        "columnName": "antigen.gene",
        "value": "BZLF1"
}, {
        "columnName": "antigen.species",
        "value": "EBV"
}, {
        "columnName": "reference.id",
        "value": "PMID:16148129"
}, {
        "columnName": "method",
        "value": "{\"frequency\": \"4/4\", \"identification\": \"antigen-loaded-targets\", \"sequencing\": \"sanger\", \"singlecell\": \"\",    \"verification\": \"antigen-loaded-targets,tetramer-stain\"}"
}, {
        "columnName": "meta",
        "value": "{\"cell.subset\": \"CD8+\", \"clone.id\": \"MW2\", \"donor.MHC\": \"HLA-B*35:01\", \"donor.MHC.method\": \"sequencing\", \"epitope.id\": \"\", \"replica.id\": \"\", \"samples.found\": 1, \"structure.id\": \"\", \"studies.found\": 1, \"study.id\": \"\", \"subject.cohort\": \"healthy\", \"subject.id\": \"\", \"tissue\": \"CTL culture\"}"
}, {
        "columnName": "cdr3fix",
        "value": "{\"cdr3\": \"CAAAASGGSYIPTF\", \"cdr3_old\": \"CAAAASGGSYIPTF\", \"fixNeeded\": false, \"good\": true, \"jCanonical\": true, \"jFixType\": \"NoFixNeeded\", \"jId\": \"TRAJ6*01\", \"jStart\": 4, \"vCanonical\": true, \"vEnd\": 2, \"vFixType\": \"NoFixNeeded\", \"vId\": \"TRAV1-2*01\"}"
}, {
        "columnName": "vdjdb.score",
        "value": "3"
}, {
        "columnName": "web.method",
        "value": "culture"
}, {
        "columnName": "web.method.seq",
        "value": "sanger"
}, {
        "columnName": "web.cdr3fix.nc",
        "value": "no"
}, {
        "columnName": "web.cdr3fix.unmp",
        "value": "no"
}]
}]

Note

Column description can be found here.

Warning

The columns method, meta, cdr3fix, web.method, web.method.seq are likely to be removed in the future.