spaces

List spaces

Get a list of all spaces that the requesting user is a member or owner of.

Request

get

/spaces

Response

{
  "example": [
    {
      "description": "The default space.",
      "id": 0,
      "name": "Space 0"
    }
  ],
  "status": "200"
}

Get a space

Fetches the complete representation of a space.

Errors

Status	Description
404	User not found

Request

get

/spaces/{space_id}

Response

{
  "example": {
    "created_at": "2015-10-06T20:00:00Z",
    "created_by": "test",
    "description": "",
    "id": 0,
    "members": [
      {
        "administrator": true,
        "handle": "bob",
        "id": "test",
        "label": null,
        "project": null,
        "reference": null,
        "role": "owner",
        "sample": null,
        "subtraction": null,
        "upload": null
      }
    ],
    "name": "Space 0",
    "updated_at": "2015-10-06T20:00:00Z"
  },
  "status": "200"
}

Update a space

Changes the name or description of a space.

Parameters

Name	Type	Required	Description
description	string	false	the description for the space
name	string	false	the unique display name for the space

Errors

Status	Description
404	User not found

Request

patch

/spaces/{space_id}

{
  "name": "My Space"
}

Response

{
  "example": {
    "created_at": "2015-10-06T20:00:00Z",
    "created_by": "test",
    "description": "",
    "id": 0,
    "members": [
      {
        "administrator": true,
        "handle": "bob",
        "id": "test",
        "label": null,
        "project": null,
        "reference": null,
        "role": "owner",
        "sample": null,
        "subtraction": null,
        "upload": null
      }
    ],
    "name": "My Space",
    "updated_at": "2015-10-06T20:00:00Z"
  },
  "status": "201"
}

List labels

Lists all sample labels on the instance. Pagination is not supported; all labels are included in the response.

Errors

Status	Description
400	Invalid query

Request

get

/spaces/{space_id}/labels

Response

{
  "status": "200"
}

Create a label

Creates a new sample label.

The color must be a valid hexadecimal code.

Parameters

Name	Type	Required	Description
color	string	false	color of the label
description	string	false	description of the document
name	string	true	unique name for the label document

Errors

Status	Description
400	Invalid Input

Request

post

/spaces/{space_id}/labels

{
  "color": "#374151",
  "description": "dsRNA/binding protein",
  "name": "Binding protein"
}

Response

{
  "example": {
    "color": "#374151",
    "count": 0,
    "description": "dsRNA/binding protein",
    "id": 23,
    "name": "Binding protein"
  },
  "status": "201"
}

Delete a label

Deletes an existing sample label.

Request

delete

/spaces/{space_id}/labels/{label_id}

Get a label

Fetches the details for a sample label.

Errors

Status	Description
404	Not found

Request

get

/spaces/{space_id}/labels/{label_id}

Response

{
  "example": {
    "color": "#6B7280",
    "count": 0,
    "description": "dsRNA/Ab",
    "id": 22,
    "name": "Ab"
  },
  "status": "200"
}

Update a label

Updates an existing sample label.

Parameters

Name	Type	Required	Description
color	string	false	A hexadecimal color for the label
description	string	false	A longer description for the label
name	string	false	A short display name

Errors

Status	Description
400	Invalid input
404	Not found

Request

patch

/spaces/{space_id}/labels/{label_id}

{
  "color": "#93C5FD",
  "description": "Field samples from 2022 harvest",
  "name": "Blueberry 2022"
}

Response

{
  "example": {
    "color": "#93C5FD",
    "count": 0,
    "description": "Field samples from 2022 harvest",
    "id": 22,
    "name": "Blueberry 2022"
  },
  "status": "200"
}

List members

Lists the members of a space and their roles.

Request

get

/spaces/{space_id}/members

Response

{
  "example": {
    "available_roles": [
      {
        "description": "Full control over space a and all resources and members.\n- Remove or add members.\n- Cancel any job.",
        "id": "owner",
        "name": "Owner"
      },
      {
        "description": "Access a space.",
        "id": "member",
        "name": "Member"
      },
      {
        "description": "Create, edit, or delete labels.",
        "id": "label_manager",
        "name": "Label_manager"
      },
      {
        "description": "Create, edit, or delete projects.",
        "id": "project_manager",
        "name": "Project_manager"
      },
      {
        "description": "Create or edit projects.",
        "id": "project_editor",
        "name": "Project_editor"
      },
      {
        "description": "View projects.",
        "id": "project_viewer",
        "name": "Project_viewer"
      },
      {
        "description": "Edit, build, contribute to (modify otus), or delete any reference. Modify access\ncontrol and settings for any reference.",
        "id": "reference_manager",
        "name": "Reference_manager"
      },
      {
        "description": "Edit, build, and contribute to any reference.",
        "id": "reference_builder",
        "name": "Reference_builder"
      },
      {
        "description": "Edit or contribute to any reference.",
        "id": "reference_editor",
        "name": "Reference_editor"
      },
      {
        "description": "Create, edit, or delete (modify) OTUs in any reference.",
        "id": "reference_contributor",
        "name": "Reference_contributor"
      },
      {
        "description": "View any and use any reference.",
        "id": "reference_viewer",
        "name": "Reference_viewer"
      },
      {
        "description": "Create, edit, or delete samples.",
        "id": "sample_manager",
        "name": "Sample_manager"
      },
      {
        "description": "Create or edit samples.",
        "id": "sample_editor",
        "name": "Sample_editor"
      },
      {
        "description": "Analyze samples.",
        "id": "sample_analyzer",
        "name": "Sample_analyzer"
      },
      {
        "description": "View samples.",
        "id": "sample_viewer",
        "name": "Sample_viewer"
      },
      {
        "description": "Create, edit, or delete subtractions.",
        "id": "subtraction_manager",
        "name": "Subtraction_manager"
      },
      {
        "description": "Edit subtractions.",
        "id": "subtraction_editor",
        "name": "Subtraction_editor"
      },
      {
        "description": "View or use subtractions.",
        "id": "subtraction_viewer",
        "name": "Subtraction_viewer"
      },
      {
        "description": "Create, use, or delete uploads.",
        "id": "upload_manager",
        "name": "Upload_manager"
      },
      {
        "description": "View or use uploads.",
        "id": "upload_viewer",
        "name": "Upload_viewer"
      }
    ],
    "items": [
      {
        "administrator": true,
        "handle": "bob",
        "id": "test",
        "label": null,
        "project": null,
        "reference": null,
        "role": "owner",
        "sample": null,
        "subtraction": null,
        "upload": null
      }
    ]
  },
  "status": "200"
}

Remove a member

Removes a member from the space. They will no longer have access to any data in the space.

Request

delete

/spaces/{space_id}/members/{member_id}

Update a member

Changes the roles of the space member.

Parameters

Name	Type	Required	Description
label		false
project		false
reference		false
role		false
sample		false
subtraction		false
upload		false

Errors

Status	Description
404	User not found

Request

patch

/spaces/{space_id}/members/{member_id}

{
  "role": "member"
}

Response

{
  "example": [
    {
      "administrator": true,
      "handle": "bob",
      "id": "test",
      "label": null,
      "project": null,
      "reference": null,
      "role": "member",
      "sample": null,
      "subtraction": null,
      "upload": null
    }
  ],
  "status": "200"
}

Find references

Lists references that match the find term.

Request

get

/spaces/{space_id}/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

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

Request

post

/spaces/{space_id}/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

/spaces/{space_id}/refs/{ref_id}

Get a reference

Fetches the details of a reference.

Errors

Status	Description
403	Not permitted
404	Not found

Request

get

/spaces/{space_id}/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

Status	Description
403	Insufficient rights
404	Not found

Request

patch

/spaces/{space_id}/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 history

Lists changes made to OTUs in the reference.

Errors

Status	Description
404	Not found

Request

get

/spaces/{space_id}/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

Status	Description
404	Not found

Request

get

/spaces/{space_id}/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

Status	Description
403	Insufficient rights
404	Not found

Request

post

/spaces/{space_id}/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

Status	Description
404	Not found

Request

get

/spaces/{space_id}/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
abbreviation	string	false
name	string	true
schema	array	false

Errors

Status	Description
400
403
404

Request

post

/spaces/{space_id}/refs/{ref_id}/otus

Response

{
  "status": "201"
}

List updates

Lists all updates made to the reference.

Request

get

/spaces/{space_id}/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

Status	Description
403	Insufficient rights
404	Not found

Request

post

/spaces/{space_id}/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

Status	Description
400	Bad request
403	Insufficient rights
404	Not found

Request

post

/spaces/{space_id}/refs/{ref_id}/users

{
  "modify_otu": true,
  "user_id": "sidney"
}

Response

{
  "status": "201"
}

Remove a user

Removes a user from the reference.

Request

delete

/spaces/{space_id}/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

Status	Description
403	Insufficient rights
404	Not found

Request

patch

/spaces/{space_id}/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"
}

Find samples

Lists samples, filtering by data passed as URL parameters.

Errors

Status	Description
400	Invalid query

Request

get

/spaces/{space_id}/samples

Response

{
  "status": "200"
}

Create a sample

Creates a new sample with the given name, labels and subtractions.

Parameters

Name	Type	Required
files	array	true
group	integer	false
host	string	false
isolate	string	false
labels	array	false
library_type		false
locale	string	false
name	string	true
notes	string	false
subtractions	array	false

Errors

Status	Description
400	Invalid input
403	Not permitted

Request

post

/spaces/{space_id}/samples

Response

{
  "example": {
    "all_read": false,
    "all_write": false,
    "artifacts": [],
    "created_at": "2022-05-20T23:48:00.901000Z",
    "format": "fastq",
    "group": {
      "id": 4,
      "name": "Sidney"
    },
    "group_read": true,
    "group_write": true,
    "hold": true,
    "host": "Malus domestica",
    "id": "9zn468u9",
    "is_legacy": false,
    "isolate": "",
    "labels": [],
    "library_type": "normal",
    "locale": "",
    "name": "HX8",
    "notes": "",
    "nuvs": false,
    "paired": true,
    "pathoscope": true,
    "quality": {
      "bases": [
        [
          36,
          37,
          37,
          37,
          37,
          37
        ],
        [
          36,
          37,
          37,
          37,
          37,
          37
        ]
      ],
      "composition": [
        [
          29,
          18,
          15,
          36.5
        ],
        [
          25.5,
          19,
          31.5,
          22
        ]
      ],
      "count": 94601674,
      "encoding": "Sanger / Illumina 1.9\n",
      "gc": 43,
      "length": [
        150,
        150
      ],
      "sequences": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        18,
        298
      ]
    },
    "reads": [
      {
        "download_url": "/samples/9zn468u9/reads/reads_1.fq.gz",
        "id": 713,
        "name": "reads_1.fq.gz",
        "name_on_disk": "reads_1.fq.gz",
        "sample": "9zn468u9",
        "size": 3540467819,
        "upload": null,
        "uploaded_at": "2022-05-21T00:10:27.418000Z"
      },
      {
        "download_url": "/samples/9zn468u9/reads/reads_2.fq.gz",
        "id": 714,
        "name": "reads_2.fq.gz",
        "name_on_disk": "reads_2.fq.gz",
        "sample": "9zn468u9",
        "size": 3321721014,
        "upload": null,
        "uploaded_at": "2022-05-21T00:11:10.743000Z"
      }
    ],
    "ready": true,
    "subtractions": [
      {
        "id": "0nhpi36p",
        "name": "Malus domestica"
      }
    ],
    "user": {
      "administrator": true,
      "handle": "mrott",
      "id": "ihvze2u9"
    },
    "workflows": {
      "aodp": "incompatible",
      "nuvs": "none",
      "pathoscope": "none"
    }
  },
  "status": "201"
}

Delete a sample

Removes a sample document and all associated analyses.

Request

delete

/spaces/{space_id}/samples/{sample_id}

Get a sample

Fetches the details for a sample.

Errors

Status	Description
403
404

Request

get

/spaces/{space_id}/samples/{sample_id}

Response

{
  "example": {
    "all_read": false,
    "all_write": false,
    "artifacts": [],
    "created_at": "2022-05-20T23:48:00.901000Z",
    "format": "fastq",
    "group": {
      "id": 4,
      "name": "Sidney"
    },
    "group_read": true,
    "group_write": true,
    "hold": true,
    "host": "Malus domestica",
    "id": "9zn468u9",
    "is_legacy": false,
    "isolate": "",
    "labels": [],
    "library_type": "normal",
    "locale": "",
    "name": "HX8",
    "notes": "",
    "nuvs": false,
    "paired": true,
    "pathoscope": true,
    "quality": {
      "bases": [
        [
          36,
          37,
          37,
          37,
          37,
          37
        ],
        [
          36,
          37,
          37,
          37,
          37,
          37
        ]
      ],
      "composition": [
        [
          29,
          18,
          15,
          36.5
        ],
        [
          25.5,
          19,
          31.5,
          22
        ]
      ],
      "count": 94601674,
      "encoding": "Sanger / Illumina 1.9\n",
      "gc": 43,
      "length": [
        150,
        150
      ],
      "sequences": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        18,
        298
      ]
    },
    "reads": [
      {
        "download_url": "/samples/9zn468u9/reads/reads_1.fq.gz",
        "id": 713,
        "name": "reads_1.fq.gz",
        "name_on_disk": "reads_1.fq.gz",
        "sample": "9zn468u9",
        "size": 3540467819,
        "upload": null,
        "uploaded_at": "2022-05-21T00:10:27.418000Z"
      },
      {
        "download_url": "/samples/9zn468u9/reads/reads_2.fq.gz",
        "id": 714,
        "name": "reads_2.fq.gz",
        "name_on_disk": "reads_2.fq.gz",
        "sample": "9zn468u9",
        "size": 3321721014,
        "upload": null,
        "uploaded_at": "2022-05-21T00:11:10.743000Z"
      }
    ],
    "ready": true,
    "subtractions": [
      {
        "id": "0nhpi36p",
        "name": "Malus domestica"
      }
    ],
    "user": {
      "administrator": true,
      "handle": "mrott",
      "id": "ihvze2u9"
    },
    "workflows": {
      "aodp": "incompatible",
      "nuvs": "none",
      "pathoscope": "none"
    }
  },
  "status": "200"
}

Update a sample

Updates a sample using its 'sample id'.

Parameters

Name	Type	Required
host	string	false
isolate	string	false
labels	array	false
locale	string	false
name	string	false
notes	string	false
subtractions	array	false

Errors

Status	Description
400	Sample name is already in use
403	Insufficient rights
404	Not found

Request

patch

/spaces/{space_id}/samples/{sample_id}

{
  "host": "Tobacco",
  "labels": [
    1,
    5,
    6
  ],
  "name": "Tobacco mosaic viru"
}

Response

{
  "example": {
    "all_read": false,
    "all_write": false,
    "artifacts": [],
    "created_at": "2022-05-20T23:48:00.901000Z",
    "format": "fastq",
    "group": {
      "id": 4,
      "name": "Sidney"
    },
    "group_read": true,
    "group_write": true,
    "hold": true,
    "host": "Tobacco",
    "id": "9zn468u9",
    "is_legacy": false,
    "isolate": "",
    "labels": [
      1,
      5,
      6
    ],
    "library_type": "normal",
    "locale": "",
    "name": "Tobacco mosaic viru",
    "notes": "",
    "nuvs": false,
    "paired": true,
    "pathoscope": true,
    "quality": {
      "bases": [
        [
          36,
          37,
          37,
          37,
          37,
          37
        ],
        [
          36,
          37,
          37,
          37,
          37,
          37
        ]
      ],
      "composition": [
        [
          29,
          18,
          15,
          36.5
        ],
        [
          25.5,
          19,
          31.5,
          22
        ]
      ],
      "count": 94601674,
      "encoding": "Sanger / Illumina 1.9\n",
      "gc": 43,
      "length": [
        150,
        150
      ],
      "sequences": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        18,
        298
      ]
    },
    "reads": [
      {
        "download_url": "/samples/9zn468u9/reads/reads_1.fq.gz",
        "id": 713,
        "name": "reads_1.fq.gz",
        "name_on_disk": "reads_1.fq.gz",
        "sample": "9zn468u9",
        "size": 3540467819,
        "upload": null,
        "uploaded_at": "2022-05-21T00:10:27.418000Z"
      },
      {
        "download_url": "/samples/9zn468u9/reads/reads_2.fq.gz",
        "id": 714,
        "name": "reads_2.fq.gz",
        "name_on_disk": "reads_2.fq.gz",
        "sample": "9zn468u9",
        "size": 3321721014,
        "upload": null,
        "uploaded_at": "2022-05-21T00:11:10.743000Z"
      }
    ],
    "ready": true,
    "subtractions": [
      {
        "id": "0nhpi36p",
        "name": "Malus domestica"
      }
    ],
    "user": {
      "administrator": true,
      "handle": "mrott",
      "id": "ihvze2u9"
    },
    "workflows": {
      "aodp": "incompatible",
      "nuvs": "none",
      "pathoscope": "none"
    }
  },
  "status": "200"
}

Find subtractions

Lists subtractions by their name or nickname by providing a term as a query parameter. Partial matches are supported.

Supports pagination unless the short query parameter is set. In this case, an array of objects containing the id and name of every subtraction is returned.

Request

get

/spaces/{space_id}/subtractions

Response

{
  "status": "200"
}

Create a subtraction

Creates a new subtraction.

A job is started to build the data necessary to make the subtraction usable in analyses. The subtraction is usable when the ready property is true.

Parameters

Name	Type	Required	Description
name	string	true	A unique name for the host (eg. Arabidopsis)
nickname	string	false	A nickname of the host
upload_id	integer	true	The unique id of the file

Errors

Status	Description
400	Upload does not exist
403	Not permitted

Request

post

/spaces/{space_id}/subtractions

{
  "name": "Foobar",
  "nickname": "foo",
  "upload_id": 1234
}

Response

{
  "example": {
    "created_at": "2015-10-06T20:00:00Z",
    "deleted": false,
    "file": {
      "id": 1234,
      "name": "test_upload"
    },
    "files": [],
    "id": "abc123",
    "linked_samples": [],
    "name": "Foobar",
    "nickname": "foo",
    "ready": false,
    "user": {
      "administrator": false,
      "handle": "bob",
      "id": "test"
    }
  },
  "status": "201"
}

Delete a subtraction

Deletes an existing subtraction.

Errors

Status	Description
403	Not permitted
404	Not found
409	Has linked samples

Request

delete

/spaces/{space_id}/subtractions/{subtraction_id}

Response

{
  "status": "204"
}

Get a subtraction

Fetches the details of a subtraction.

Errors

Status	Description
404	Not found

Request

get

/spaces/{space_id}/subtractions/{subtraction_id}

Response

{
  "example": {
    "count": 9,
    "created_at": "2021-12-21T23:52:13.185000Z",
    "deleted": false,
    "file": {
      "id": 58,
      "name": "arabidopsis_thaliana_+_plastids.fa.gz"
    },
    "files": [
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.1.bt2",
        "id": 39,
        "name": "subtraction.1.bt2",
        "size": 44200803,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.2.bt2",
        "id": 37,
        "name": "subtraction.2.bt2",
        "size": 30000964,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.3.bt2",
        "id": 42,
        "name": "subtraction.3.bt2",
        "size": 3275,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.4.bt2",
        "id": 40,
        "name": "subtraction.4.bt2",
        "size": 30000958,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.fa.gz",
        "id": 36,
        "name": "subtraction.fa.gz",
        "size": 36160657,
        "subtraction": "q0ek30si",
        "type": "fasta"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.rev.1.bt2",
        "id": 41,
        "name": "subtraction.rev.1.bt2",
        "size": 44200803,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.rev.2.bt2",
        "id": 38,
        "name": "subtraction.rev.2.bt2",
        "size": 30000964,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      }
    ],
    "gc": {
      "a": 0.319,
      "c": 0.18,
      "g": 0.18,
      "n": 0.002,
      "t": 0.319
    },
    "id": "q0ek30si",
    "linked_samples": [
      {
        "id": "2izth91q",
        "name": "21BP074"
      },
      {
        "id": "noni4fpk",
        "name": "21BP075"
      },
      {
        "id": "o3ldvwpm",
        "name": "22SP001-M"
      },
      {
        "id": "gobtw98t",
        "name": "22SP001-R"
      }
    ],
    "name": "Arabidopsis thaliana",
    "nickname": "",
    "ready": true,
    "user": {
      "administrator": true,
      "handle": "igboyes",
      "id": "igboyes"
    }
  },
  "status": "200"
}

Update a subtraction

Updates the name or nickname of an existing subtraction.

Parameters

Name	Type	Required	Description
name	string	false	A unique name for the host
nickname	string	false	A nickname for the host

Errors

Status	Description
400	Invalid input
403	Not permitted
404	Not found

Request

patch

/spaces/{space_id}/subtractions/{subtraction_id}

{
  "name": "Arabidopsis",
  "nickname": "Thale cress"
}

Response

{
  "example": {
    "count": 9,
    "created_at": "2021-12-21T23:52:13.185000Z",
    "deleted": false,
    "file": {
      "id": 58,
      "name": "arabidopsis_thaliana_+_plastids.fa.gz"
    },
    "files": [
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.1.bt2",
        "id": 39,
        "name": "subtraction.1.bt2",
        "size": 44200803,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.2.bt2",
        "id": 37,
        "name": "subtraction.2.bt2",
        "size": 30000964,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.3.bt2",
        "id": 42,
        "name": "subtraction.3.bt2",
        "size": 3275,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.4.bt2",
        "id": 40,
        "name": "subtraction.4.bt2",
        "size": 30000958,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.fa.gz",
        "id": 36,
        "name": "subtraction.fa.gz",
        "size": 36160657,
        "subtraction": "q0ek30si",
        "type": "fasta"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.rev.1.bt2",
        "id": 41,
        "name": "subtraction.rev.1.bt2",
        "size": 44200803,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      },
      {
        "download_url": "/subtractions/q0ek30si/files/subtraction.rev.2.bt2",
        "id": 38,
        "name": "subtraction.rev.2.bt2",
        "size": 30000964,
        "subtraction": "q0ek30si",
        "type": "bowtie2"
      }
    ],
    "gc": {
      "a": 0.319,
      "c": 0.18,
      "g": 0.18,
      "n": 0.002,
      "t": 0.319
    },
    "id": "q0ek30si",
    "linked_samples": [
      {
        "id": "2izth91q",
        "name": "21BP074"
      },
      {
        "id": "noni4fpk",
        "name": "21BP075"
      },
      {
        "id": "o3ldvwpm",
        "name": "22SP001-M"
      },
      {
        "id": "gobtw98t",
        "name": "22SP001-R"
      }
    ],
    "name": "Arabidopsis",
    "nickname": "Thale cress",
    "ready": true,
    "user": {
      "administrator": true,
      "handle": "igboyes",
      "id": "igboyes"
    }
  },
  "status": "200"
}

List uploads

Lists JSON details of all files uploaded to the instance.

Request

get

/spaces/{space_id}/uploads

Response

{
  "status": "200"
}

Upload a file

Accepts file uploads as multipart requests. The request should contain a single field file containing the file data.

A file name and type must be included in the query string.

Errors

Status	Description
401	Requires authorization
403	Not permitted
404	Not found

Request

post

/spaces/{space_id}/uploads

Response

{
  "example": {
    "created_at": "2022-01-22T17:28:21.491000Z",
    "id": 106,
    "name": "MPI19_L3_2.fq.gz",
    "name_on_disk": "106-MPI19_L3_2.fq.gz",
    "ready": true,
    "removed": false,
    "removed_at": null,
    "reserved": true,
    "size": 3356803271,
    "type": "reads",
    "uploaded_at": "2022-01-22T17:31:59.801000Z",
    "user": {
      "administrator": true,
      "handle": "mrott",
      "id": "ihvze2u9"
    }
  },
  "status": "201"
}

Delete an upload

Deletes an upload using its 'upload id'.

Errors

Status	Description
401	Requires authorization
403	Not permitted
404	Not found

Request

delete

/spaces/{space_id}/uploads/{upload_id}

Response

{
  "status": "204"
}

Download an upload

Downloads a previously uploaded file.

Headers: Content-Disposition: attachment; filename= Content-Type: application/octet-stream

Errors

Status	Description
404	Not found

Request

get

/spaces/{space_id}/uploads/{upload_id}

Response

{
  "status": "200"
}

overview

API

List spaces

Response

Get a space

Errors

Response

Update a space

Parameters

Errors

Response

List labels

Errors

Response

Create a label

Parameters

Errors

Response

Delete a label

Get a label

Errors

Response

Update a label

Parameters

Errors

Response

List members

Response

Remove a member

Update a member

Parameters

Errors

Response

Find references

Response

Create a reference

Parameters

Errors

Response

Delete a reference

Get a reference

Errors

Response

Update a reference

Parameters

Errors

Response

List history

Errors

Response

List indexes

Errors

Response

Create an index

Errors

Response

Find OTUs

Errors

Response

Create OTU

Parameters

Errors

Response

List updates

Response

Update a reference

Errors

Response

Add a user

Parameters

Errors

Response

Remove a user

Update a user

Parameters

Errors

Response

Find samples

Errors

Response