Legacy API Docs. These docs are for Virtool 4.3.3.

Samples

Find

Find samples based on the sample name or creator username.

GET

/api/samples

Parameters

Name	Type	Default	Description
find	string		sample name or username to filter by
page	integer	1	page number of results to return
per_page	integer	15	number of documents to return per page

Example

GET /api/samples?find=test&page=1

Response

Status: 200 OK

{
  "documents": [
    {
      "name": "Test 1",
      "isolate": "",
      "host": "",
      "nuvs": true,
      "pathoscope": true,
      "created_at": "2018-02-01T00:29:44.867000Z",
      "imported": false,
      "archived": false,
      "user": {
        "id": "igboyes"
      },
      "id": "htosefxu"
    }
  ],
  "total_count": 1,
  "found_count": 1,
  "page_count": 1,
  "per_page": 15,
  "page": 1
}

Errors

Status	Message	Reason
422	Invalid query	invalid URL query fields or values

Get

Requires read permission on reference

Get the complete representation of a sample.

GET

/api/samples/:id

Example

GET /api/samples/htosefxu

Response

Status: 200 OK

{
	"name": "Test 1",
	"isolate": "",
	"host": "",
	"locale": "",
	"subtraction": {
		"id": "Arabidopsis"
	},
	"files": [
		"jekfyjur-S00196E_AGTCAA_L007_R1.fq"
	],
	"group": "none",
	"nuvs": true,
	"pathoscope": true,
	"created_at": "2018-02-01T00:29:44.867000Z",
	"format": "fastq",
	"imported": false,
	"quality": {
		"count": 2086040,
		"encoding": "Sanger / Illumina 1.9\n",
		"length": [
			50,
			101
		],
		"gc": 49.0,
		"bases": [
			[32, 34, 33, 34, 31, 34], ...
        ],
		"sequences": [
			0, ...
        ],
		"composition": [
			[27, 14, 12, 45], ...
        ]
	},
	"analyzed": false,
	"hold": true,
	"archived": false,
	"group_read": true,
	"group_write": false,
	"all_read": true,
	"all_write": false,
	"user": {
		"id": "igboyes"
	},
	"id": "htosefxu"
}

Errors

Status	Message	Reason
403	Insufficient rights	client does not have the required rights to read the sample
404	Not found	`sample_id` in URL does not exist

Create

Requires create_sample permission

Creates a sample record and starts a job that populates the record from a FASTQ file stored in the file manager.

The array of files must contain only one or two items. Samples with arrays containing one item will be assumed to by derived from single-end libraries, while arrays with two items will correspond to paired-end libraries.

POST

/api/samples

Input

Name	Type	Required	Description
name	string	true	a unique name for the sample
host	string	false	the exact (not subtraction) host
isolate	string	false	the originating isolate
locale	string	false	the location in which the sample was collected
subtraction	string	true	the `id` of a previously imported subtraction genome
files	array	true	ids of previously uploaded files

Example

POST /api/samples

{
  "name": "Test A",
  "host": "Tree",
  "isolate": "Isolate A-1",
  "locale": "Earth",
  "subtraction": "Arabidopsis",
  "files": ["sibvzhqc-S00196E_AGTCAA_L007_R1.fq"]
}

Response

Status: 201 Created

{
  "name": "Test A",
  "host": "Tree",
  "isolate": "Isolate A-1",
  "locale": "Earth",
  "subtraction": {
    "id": "Arabidopsis"
  },
  "files": ["sibvzhqc-S00196E_AGTCAA_L007_R1.fq"],
  "group": "none",
  "nuvs": false,
  "pathoscope": false,
  "created_at": "2018-02-07T00:25:53.786000Z",
  "format": "fastq",
  "imported": "ip",
  "quality": null,
  "analyzed": false,
  "hold": true,
  "archived": false,
  "group_read": true,
  "group_write": false,
  "all_read": true,
  "all_write": false,
  "user": {
    "id": "igboyes"
  },
  "id": "oggjipxw"
}

Errors

Status	Message	Reason
400	File does not exist	the provided `file_id` does not exist
400	Group does not exist	`group` in POST body does not exist
400	Group value required for sample creation	the server is configured to required group assignment of samples on creation
400	Sample name is already in use	the provided `name` is already assigned to an existing sample
400	Subtraction does not exist	`subtraction` in POST body does not exist
403	Not permitted	client does not have the `create_sample` permission
422	Invalid input	JSON request body is invalid

Edit

Requires write permission on reference

Update modifiable fields of a sample.

PATCH

/api/samples/:id

Input

Name	Type	Description
name	string	the sample name
host	string	the exact (not subtraction) host
isolate	string	the originating isolate
locale	string	the location in which the sample was collected

Example

PATCH /api/samples/oggjipxw

{
  "name": "Test A",
  "host": "Vine",
  "isolate": "Isolate A1",
  "locale": ""
}

Response

Status: 200 OK

{
  "name": "Test A",
  "host": "Vine",
  "isolate": "Isolate A1",
  "nuvs": false,
  "pathoscope": false,
  "created_at": "2018-02-07T00:25:53.786000Z",
  "imported": false,
  "archived": false,
  "user": {
    "id": "igboyes"
  },
  "id": "oggjipxw"
}

Errors

Status	Message	Reason
400	Sample name is already in use	the provided `name` is already assigned to an existing sample
403	Insufficient rights	client does not have the required rights to edit the sample
404	Not found	`sample_id` in URL does not exist
422	Invalid input	request body JSON failed validation

Edit Rights

Role Administrator or Owner

Edit the access rights for a sample.

PATCH

/api/samples/:id/rights

Input

Name	Type	Description
group	string	the owner `group_id`
group_read	boolean	group can read sample
group_write	boolean	group can modify sample
all_read	boolean	all users can read sample
all_write	boolean	all users can modify sample

Example

PATCH /api/samples/oggjipxw/rights

{
  "group": "administrator",
  "group_read": true,
  "group_write": true
}

Response

Status: 200 OK

{
  "group": "administrator",
  "group_read": true,
  "group_write": true,
  "all_read": true,
  "all_write": false
}

Errors

Status	Message	Reason
400	Group does not exist	user group does not exist in instance
403	Must be administrator or sample owner	user is neither the sample owner nor an administrator
404	Not found	`sample_id` in URL does not exist
422	Invalid input	request body JSON failed validation

Replace Files

Requires write permission on reference

Replace old trimmed files with original raw files.

Remove

Role Administrator or Owner

Remove an existing sample record and its associated data files.

DELETE

/api/samples/:id

Example

DELETE /api/samples/oggjipxw

Response

Status: 204 No Content

Errors

Status	Message	Reason
403	Insufficient rights	client does not have the required rights to remove the sample
404	Not found	`sample_id` in URL does not exist

List Analyses

Requires read permission on reference

Retrieve a summary list of analyses associated with a sample.

Returned documents do not include diagnostic data. Use the analyses endpoints for more extensive modification and querying of analysis data.

GET

/api/samples/:id/analyses

Example

GET /api/samples/htosefxu/analyses

Response

Status: 200 OK

{
  "total_count": 2,
  "documents": [
    {
      "ready": true,
      "created_at": "2018-02-06T19:32:59.533000Z",
      "job": {
        "id": "khjhwnlf"
      },
      "algorithm": "nuvs",
      "sample": {
        "id": "htosefxu",
        "name": "Test 1"
      },
      "index": {
        "id": "jiwncaqr",
        "version": 0
      },
      "user": {
        "id": "igboyes"
      },
      "id": "yzgqgbld"
    },
    {
      "ready": true,
      "created_at": "2018-02-06T22:15:37.411000Z",
      "job": {
        "id": "dqswirty"
      },
      "algorithm": "pathoscope_bowtie",
      "sample": {
        "id": "htosefxu",
        "name": "Test 1"
      },
      "index": {
        "id": "bznqwjsa",
        "version": 1
      },
      "user": {
        "id": "igboyes"
      },
      "id": "xfvpxvwi"
    }
  ]
}

Errors

Status	Message	Reason
403	Insufficient rights	client does not have the required rights to view the sample analyses
404	Not found	`sample_id` in URL does not exist

Analyze

Requires write permission on reference

Immediately create and placeholder analysis record for a sample and start an analysis job. When the job succeeds the analysis document will be populated.

POST

/api/samples/:id/analyses

Input

Name	Type	Required	Description
algorithm	string	True	the algorithm name (eg. pathoscope_bowtie)
ref_id	string	True	the reference to run the analysis against

Example

POST /api/samples/htosefxu/analyses

{
  "algorithm": "pathoscope_bowtie",
  "ref_id": "foo"
}

Response

Status: 201 Created

{
  "ready": false,
  "created_at": "2018-02-07T17:50:44.508000Z",
  "job": {
    "id": "kizfvroe"
  },
  "algorithm": "pathoscope_bowtie",
  "sample": {
    "id": "htosefxu"
  },
  "index": {
    "id": "bznqwjsa",
    "version": 1
  },
  "user": {
    "id": "igboyes"
  },
  "id": "fbzypgva"
}

Errors

Status	Message	Reason
400	Reference does not exist	specified `ref_id` not found
400	No index is ready for the reference	the reference doesn’t have a built index ready for analysis
403	Insufficient rights	client does not have the required rights to create a new analysis for the sample
404	Not found	`sample_id` in URL does not exist
422	Invalid input	the JSON request body is invalid