References

Find references

Lists references that match the find term.

Request

get
/refs

Response

{
  "example": {
    "documents": [
      {
        "cloned_from": {
          "id": "pat6xdn3",
          "name": "Plant Viruses"
        },
        "created_at": "2022-01-28T23:42:48.321000Z",
        "data_type": "genome",
        "groups": [
          {
            "build": false,
            "created_at": "2022-06-10T20:00:34.129000Z",
            "id": "sidney",
            "modify": false,
            "modify_otu": false,
            "remove": false
          }
        ],
        "id": "d19exr83",
        "internal_control": null,
        "latest_build": {
          "created_at": "2022-07-05T17:41:51.857000Z",
          "has_json": false,
          "id": "u3lm1rk8",
          "user": {
            "administrator": true,
            "handle": "mrott",
            "id": "ihvze2u9"
          },
          "version": 14
        },
        "name": "New Plant Viruses",
        "organism": "virus",
        "otu_count": 2102,
        "task": {
          "id": 331
        },
        "unbuilt_change_count": 4,
        "user": {
          "id": "igboyes"
        },
        "users": [
          {
            "build": true,
            "id": "igboyes",
            "modify": true,
            "modify_otu": true,
            "remove": true
          }
        ]
      }
    ],
    "found_count": 2,
    "official_installed": true,
    "page": 1,
    "page_count": 1,
    "per_page": 25,
    "total_count": 2
  },
  "status": "200"
}

Create a reference

Creates an empty reference.

Parameters

Name Type Required Description
clone_from string false a valid ref_id that the new reference should be cloned from
data_type string false the sequence data type
description string false a longer description for the reference
import_from string false a valid file_id that the new reference should be imported from
name string false the virus name
organism string false the organism
release_id string false the id of the GitHub release to install
remote_from string false a valid GitHub slug to download and update the new reference from

Errors

StatusDescription
400 Source reference does not exist
403 Not permitted
502 Could not reach GitHub

Request

post
/refs
{
  "data_type": "genome",
  "name": "Plant Viruses",
  "organism": "viruses"
}

Response

{
  "example": {
    "cloned_from": {
      "id": "pat6xdn3",
      "name": "Plant Viruses"
    },
    "contributors": [
      {
        "administrator": true,
        "count": 6,
        "handle": "reece",
        "id": "hjol9wdt"
      },
      {
        "administrator": true,
        "count": 7906,
        "handle": "mrott",
        "id": "ihvze2u9"
      },
      {
        "administrator": true,
        "count": 1563,
        "handle": "igboyes",
        "id": "igboyes"
      },
      {
        "administrator": true,
        "count": 2483,
        "handle": "jasper",
        "id": "1kg24j7t"
      }
    ],
    "created_at": "2022-01-28T23:42:48.321000Z",
    "data_type": "genome",
    "description": "",
    "groups": [
      {
        "build": false,
        "created_at": "2022-06-10T20:00:34.129000Z",
        "id": "sidney",
        "modify": false,
        "modify_otu": false,
        "remove": false
      }
    ],
    "id": "d19exr83",
    "internal_control": null,
    "latest_build": {
      "created_at": "2022-07-05T17:41:51.857000Z",
      "has_json": false,
      "id": "u3lm1rk8",
      "user": {
        "administrator": true,
        "handle": "mrott",
        "id": "ihvze2u9"
      },
      "version": 14
    },
    "name": "Plant Viruses",
    "organism": "viruses",
    "otu_count": 2102,
    "restrict_source_types": false,
    "source_types": [
      "isolate",
      "strain"
    ],
    "task": {
      "id": 331
    },
    "unbuilt_change_count": 4,
    "user": {
      "administrator": true,
      "handle": "igboyes",
      "id": "igboyes"
    },
    "users": [
      {
        "administrator": true,
        "build": true,
        "handle": "igboyes",
        "id": "igboyes",
        "modify": true,
        "modify_otu": true,
        "remove": true
      }
    ]
  },
  "status": "200"
}

Delete a reference

Deletes a reference and its associated OTUs, history, and indexes. Deleting a reference does not break dependent analyses and other resources.

Request

delete
/refs/{ref_id}

Get a reference

Fetches the details of a reference.

Errors

StatusDescription
403 Not permitted
404 Not found

Request

get
/refs/{ref_id}

Response

{
  "example": {
    "cloned_from": {
      "id": "pat6xdn3",
      "name": "Plant Viruses"
    },
    "created_at": "2022-01-28T23:42:48.321000Z",
    "data_type": "genome",
    "groups": [
      {
        "build": false,
        "created_at": "2022-06-10T20:00:34.129000Z",
        "id": "sidney",
        "modify": false,
        "modify_otu": false,
        "remove": false
      }
    ],
    "id": "d19exr83",
    "internal_control": null,
    "latest_build": {
      "created_at": "2022-07-05T17:41:51.857000Z",
      "has_json": false,
      "id": "u3lm1rk8",
      "user": {
        "administrator": true,
        "handle": "mrott",
        "id": "ihvze2u9"
      },
      "version": 14
    },
    "name": "New Plant Viruses",
    "organism": "virus",
    "otu_count": 2102,
    "task": {
      "id": 331
    },
    "unbuilt_change_count": 4,
    "user": {
      "id": "igboyes"
    },
    "users": [
      {
        "build": true,
        "id": "igboyes",
        "modify": true,
        "modify_otu": true,
        "remove": true
      }
    ]
  },
  "status": "200"
}

Update a reference

Updates an existing reference.

Parameters

Name Type Required Description
description string false a longer description for the reference
internal_control string false set the OTU identified by the passed id as the internal control for the reference
name string false the virus name
organism string false the organism
restrict_source_types boolean false option to restrict source types
source_types array false source types
targets array false list of target sequences

Errors

StatusDescription
403 Insufficient rights
404 Not found

Request

patch
/refs/{ref_id}
{
  "internal_control": "ah4m5jqz",
  "name": "Regulated Pests",
  "organism": "phytoplasma"
}

Response

{
  "example": {
    "cloned_from": {
      "id": "pat6xdn3",
      "name": "Plant Viruses"
    },
    "created_at": "2022-01-28T23:42:48.321000Z",
    "data_type": "genome",
    "groups": [
      {
        "build": false,
        "created_at": "2022-06-10T20:00:34.129000Z",
        "id": "sidney",
        "modify": false,
        "modify_otu": false,
        "remove": false
      }
    ],
    "id": "d19exr83",
    "internal_control": "ah4m5jqz",
    "latest_build": {
      "created_at": "2022-07-05T17:41:51.857000Z",
      "has_json": false,
      "id": "u3lm1rk8",
      "user": {
        "administrator": true,
        "handle": "mrott",
        "id": "ihvze2u9"
      },
      "version": 14
    },
    "name": "Regulated Pests",
    "organism": "phytoplasma",
    "otu_count": 2102,
    "task": {
      "id": 331
    },
    "unbuilt_change_count": 4,
    "user": {
      "id": "igboyes"
    },
    "users": [
      {
        "build": true,
        "id": "igboyes",
        "modify": true,
        "modify_otu": true,
        "remove": true
      }
    ]
  },
  "status": "200"
}

List groups

Lists all groups that have access to the reference.

Errors

StatusDescription
404 Not found

Request

get
/refs/{ref_id}/groups

Response

{
  "example": [
    {
      "build": false,
      "created_at": "2022-06-10T20:00:34.129000Z",
      "id": 5,
      "modify": false,
      "modify_otu": false,
      "remove": false
    }
  ],
  "status": "200"
}

Add a group

Adds a group to the reference. Groups can view, use, and modify the reference.

Parameters

Name Type Required Description
build boolean false allow members to build new indexes for the reference
group_id integer true the id of the group to add
modify boolean false allow members to modify the reference metadata and settings
modify_otu boolean false allow members to modify the reference’s member OTUs
remove boolean false allow members to remove the reference

Errors

StatusDescription
400 Bad request
403 Insufficient rights
404 Not found

Request

post
/refs/{ref_id}/groups
{
  "group_id": 2,
  "modify_otu": true
}

Response

{
  "example": [
    {
      "build": false,
      "created_at": "2022-06-10T20:00:34.129000Z",
      "id": 5,
      "modify": false,
      "modify_otu": true,
      "remove": false
    }
  ],
  "status": "201"
}

Delete a group

Deletes a group from the reference.

Request

delete
/refs/{ref_id}/groups/{group_id}

Get a group

Fetches the details of a group that has access to the reference.

Errors

StatusDescription
404 Not found

Request

get
/refs/{ref_id}/groups/{group_id}

Response

{
  "example": {
    "build": false,
    "created_at": "2022-06-10T20:00:34.129000Z",
    "id": 4,
    "modify": false,
    "modify_otu": false,
    "remove": false
  },
  "status": "200"
}

Update a group

Updates the access rights a group has on the reference.

Parameters

Name Type Required Description
build boolean false allow members to build new indexes for the reference
modify boolean false allow members to modify the reference metadata and settings
modify_otu boolean false allow members to modify the reference’s member OTUs
remove boolean false allow members to remove the reference

Errors

StatusDescription
403 Insufficient rights
404 Not found

Request

patch
/refs/{ref_id}/groups/{group_id}
{
  "build": true,
  "modify": true
}

Response

{
  "example": {
    "build": true,
    "created_at": "2022-06-10T20:00:34.129000Z",
    "id": 4,
    "modify": true,
    "modify_otu": false,
    "remove": false
  },
  "status": "200"
}

List history

Lists changes made to OTUs in the reference.

Errors

StatusDescription
404 Not found

Request

get
/refs/{ref_id}/history

Response

{
  "example": {
    "documents": [
      {
        "created_at": "2022-01-28T23:28:53.881000Z",
        "description": "Removed Betaflexivirus from Camelia #1 (BFV_CAM1)",
        "id": "1wfc5x6e.removed",
        "index": {
          "id": "s7frhn8n",
          "version": 1
        },
        "method_name": "remove",
        "otu": {
          "id": "1wfc5x6e",
          "name": "Betaflexivirus from Camelia #1",
          "version": "removed"
        },
        "reference": {
          "id": "pat6xdn3"
        },
        "user": {
          "administrator": true,
          "handle": "igboyes",
          "id": "igboyes"
        }
      }
    ],
    "found_count": 1419,
    "page": 1,
    "page_count": 710,
    "per_page": 1,
    "total_count": 1419
  },
  "status": "200"
}

List indexes

Lists indexes that have been created for the reference.

Errors

StatusDescription
404 Not found

Request

get
/refs/{ref_id}/indexes

Response

{
  "example": {
    "change_count": 12,
    "documents": [
      {
        "change_count": 4,
        "created_at": "2015-10-06T20:00:00Z",
        "has_files": true,
        "id": "bar",
        "job": {
          "id": "bar"
        },
        "modified_otu_count": 3,
        "ready": false,
        "reference": {
          "id": "bar"
        },
        "user": {
          "administrator": false,
          "handle": "leeashley",
          "id": "bf1b993c"
        },
        "version": 1
      },
      {
        "change_count": 2,
        "created_at": "2015-10-06T20:00:00Z",
        "has_files": true,
        "id": "foo",
        "job": {
          "id": "foo"
        },
        "modified_otu_count": 2,
        "ready": false,
        "reference": {
          "id": "foo"
        },
        "user": {
          "administrator": false,
          "handle": "leeashley",
          "id": "bf1b993c"
        },
        "version": 0
      }
    ],
    "found_count": 2,
    "modified_otu_count": 3,
    "page": 1,
    "page_count": 1,
    "per_page": 25,
    "total_count": 2,
    "total_otu_count": 123
  },
  "status": "200"
}

Create an index

Starts a job to rebuild the otus Bowtie2 index on disk.

Does a check to make sure there are no unverified OTUs in the collection and updates otu history to show the version and id of the new index.

Errors

StatusDescription
403 Insufficient rights
404 Not found

Request

post
/refs/{ref_id}/indexes

Response

{
  "example": {
    "change_count": 0,
    "created_at": "2015-10-06T20:00:00Z",
    "has_files": true,
    "id": "fb085f7f",
    "job": {
      "id": "bf1b993c"
    },
    "modified_otu_count": 0,
    "ready": false,
    "reference": {
      "id": "foo"
    },
    "user": {
      "administrator": false,
      "handle": "bob",
      "id": "test"
    },
    "version": 9
  },
  "status": "201"
}

Find OTUs

Lists OTUs by name or abbreviation. Results are paginated.

Errors

StatusDescription
404 Not found

Request

get
/refs/{ref_id}/otus

Response

{
  "example": {
    "documents": [
      {
        "abbreviation": "ABTV",
        "id": "k77wgf8x",
        "name": "Abaca bunchy top virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 18
      },
      {
        "abbreviation": "AbBV",
        "id": "7hpwj4yh",
        "name": "Abutilon Brazil virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 4
      },
      {
        "abbreviation": "",
        "id": "p9ohme8k",
        "name": "Abutilon golden mosaic Yucatan virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 3
      },
      {
        "abbreviation": "AbMBoV",
        "id": "qrspg5w3",
        "name": "Abutilon mosaic Bolivia virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 6
      },
      {
        "abbreviation": "AbMoBrV",
        "id": "yb7kpm43",
        "name": "Abutilon mosaic Brazil virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 4
      },
      {
        "abbreviation": "AbMV",
        "id": "8540rw7b",
        "name": "Abutilon mosaic virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 9
      },
      {
        "abbreviation": "",
        "id": "3zwrpu3y",
        "name": "Abutilon yellow mosaic virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 1
      },
      {
        "abbreviation": "AcLV",
        "id": "30n6qo2x",
        "name": "Aconitum latent virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 1
      },
      {
        "abbreviation": "",
        "id": "x5qw901r",
        "name": "Actinidia chlorotic ringspot associated virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 5
      },
      {
        "abbreviation": "",
        "id": "ss6bios9",
        "name": "Actinidia emaravirus 2",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 13
      },
      {
        "abbreviation": "",
        "id": "nn5gt7db",
        "name": "Actinidia seed borne latent virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 3
      },
      {
        "abbreviation": "",
        "id": "xo3khtnd",
        "name": "Actinidia virus 1",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 2
      },
      {
        "abbreviation": "AVA",
        "id": "qg8optks",
        "name": "Actinidia virus A",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 1
      },
      {
        "abbreviation": "AVB",
        "id": "fnhtwiux",
        "name": "Actinidia virus B",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 1
      },
      {
        "abbreviation": "AVX",
        "id": "5uh1jzzk",
        "name": "Actinidia virus X",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 1
      },
      {
        "abbreviation": "AYV1",
        "id": "7ag9wwrr",
        "name": "Actinidia yellowing virus 1",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 3
      },
      {
        "abbreviation": "AYV2",
        "id": "f87f3cs7",
        "name": "Actinidia yellowing virus 2",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 3
      },
      {
        "abbreviation": "",
        "id": "e2xpkmgy",
        "name": "Adonis mosaic virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 3
      },
      {
        "abbreviation": "",
        "id": "3ly2pqbk",
        "name": "Aeonium ringspot virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 0
      },
      {
        "abbreviation": "",
        "id": "3xa1dbt0",
        "name": "African cassava mosaic Burkina Faso virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 5
      },
      {
        "abbreviation": "ACMV",
        "id": "0ommwgyh",
        "name": "African cassava mosaic virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 9
      },
      {
        "abbreviation": "",
        "id": "iyw0y3ta",
        "name": "African eggplant mosaic virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 3
      },
      {
        "abbreviation": "",
        "id": "set9w2zc",
        "name": "African eggplant yellowing virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 3
      },
      {
        "abbreviation": "AOPRV",
        "id": "taecz4c9",
        "name": "African oil palm ringspot virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 2
      },
      {
        "abbreviation": "",
        "id": "zgsytbul",
        "name": "Agave tequilana leaf virus",
        "reference": {
          "id": "d19exr83"
        },
        "verified": true,
        "version": 2
      }
    ],
    "found_count": 2102,
    "modified_count": 1,
    "page": 1,
    "page_count": 85,
    "per_page": 25,
    "total_count": 2102
  },
  "status": "200"
}

Create OTU

Creates an OTU.

Parameters

Name Type Required Description
abbreviation string false
name string true
schema array false

Errors

StatusDescription
400
403
404

Request

post
/refs/{ref_id}/otus

Response

{
  "status": "201"
}

Get latest update

Fetches the latest remote reference update from GitHub.

Also updates the reference document. This is the only way of doing so without waiting for an automatic refresh every 10 minutes.

Request

get
/refs/{ref_id}/release

Response

{
  "example": {
    "body": "#### Changed\r\n- add new isolates to Cucurbit chlorotic yellows virus",
    "content_type": "application/gzip",
    "download_url": "https://github.com/virtool/ref-plant-viruses/releases/download/v0.1.2/reference.json.gz",
    "etag": "W/\"b7e8a7fb0fbe0cade0d6a86c9e0d4549\"",
    "filename": "reference.json.gz",
    "html_url": "https://github.com/virtool/ref-plant-viruses/releases/tag/v0.1.2",
    "id": 11449913,
    "name": "v0.1.2",
    "newer": true,
    "published_at": "2018-06-12T21:52:33Z",
    "retrieved_at": "2018-06-14T19:52:17.465000Z",
    "size": 3699729
  },
  "status": "200"
}

List updates

Lists all updates made to the reference.

Request

get
/refs/{ref_id}/updates

Response

{
  "example": [
    {
      "body": "#### Fixed\r\n- fixed uploading to GitHub releases in `.travis.yml`",
      "created_at": "2018-06-14T18:37:54.242000Z",
      "filename": "reference.json.gz",
      "html_url": "https://github.com/virtool/ref-plant-viruses/releases/tag/v0.1.1",
      "id": 11447367,
      "name": "v0.1.1",
      "published_at": "2018-06-12T19:20:57Z",
      "ready": true,
      "size": 3695872,
      "user": {
        "id": "igboyes"
      }
    }
  ],
  "status": "200"
}

Update a reference

Updates the reference to the last version of the linked remote reference.

Errors

StatusDescription
403 Insufficient rights
404 Not found

Request

post
/refs/{ref_id}/updates

Response

{
  "example": {
    "body": "The release consists of a gzipped JSON file containing:\r\n\r\n- a `data_type` field with value _genome_\r\n- an `organism` field with value _virus_\r\n- the `version` name (eg. *v0.2.0*)\r\n- a timestamp with the key `created_at`\r\n- virus data compatible for import into Virtool v2.0.0+\r\n\r\nScripts have been updated to follow upcoming convention changes in Virtool v3.0.0.",
    "content_type": "application/gzip",
    "download_url": "https://github.com/virtool/virtool-database/releases/download/v0.3.0/reference.json.gz",
    "etag": "W/\"ef123d746a33f88ee44203d3ca6bc2f7\"",
    "filename": "reference.json.gz",
    "html_url": "https://api.github.com/repos/virtool/virtool-database/releases/10742520",
    "id": 10742520,
    "name": "v0.3.0",
    "newer": true,
    "published_at": "2018-04-26T19:35:33Z",
    "retrieved_at": "2018-04-14T19:52:17.465000Z",
    "size": 3709091
  },
  "status": "201"
}

Add a user

Adds a user to the reference. Users can view, use, and modify the reference.

Parameters

Name Type Required Description
build boolean false allow members to build new indexes for the reference
modify boolean false allow members to modify the reference metadata and settings
modify_otu boolean false allow members to modify the reference’s member OTUs
remove boolean false allow members to remove the reference
user_id string true the id of the user to add

Errors

StatusDescription
400 Bad request
403 Insufficient rights
404 Not found

Request

post
/refs/{ref_id}/users
{
  "modify_otu": true,
  "user_id": "sidney"
}

Response

{
  "status": "201"
}

Remove a user

Removes a user from the reference.

Request

delete
/refs/{ref_id}/users/{user_id}

Update a user

Updates the access rights a user has on the reference.

Parameters

Name Type Required Description
build boolean false allow members to build new indexes for the reference
modify boolean false allow members to modify the reference metadata and settings
modify_otu boolean false allow members to modify the reference’s member OTUs
remove boolean false allow members to remove the reference

Errors

StatusDescription
403 Insufficient rights
404 Not found

Request

patch
/refs/{ref_id}/users/{user_id}
{
  "build": true,
  "modify": true
}

Response

{
  "example": {
    "build": true,
    "created_at": "2022-06-10T20:00:34.129000Z",
    "id": 4,
    "modify": true,
    "modify_otu": false,
    "remove": false
  },
  "status": "200"
}