Start a bulk DRS import job

This API call lets you perform a bulk file import through Data Repository Service (DRS).

Before you start using this API call, please read the following important notes:

The maximum number of items to import per single API call is 100.
The rate limit for this API call is 500 files in 5 minutes. If the limit is reached and there are items left to be imported, the import will continue automatically after the five-minute period expires.
Importing DRS bundles is supported.

https://cavatica-api.sbgenomics.com/v2/bulk/drs/imports/create

Request

Example request

POST v2/bulk/drs/imports/create HTTP/1.1
Host: cavatica-api.sbgenomics.com
X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74
Content-Type: application/json

curl --data '@import.json' -X POST -H "X-SBG-Auth-Token: 3259c50e1ac5426ea8f1273259740f74" -H "Content-Type: application/json" 'https://cavatica-api.sbgenomics.com/v2/bulk/drs/imports/create HTTP/1.1'

Header Fields

Key	Description of value
`X-SBG-Auth-Token` required	Your CAVATICA authentication token.
`Content-type` required	Use `application/json`

Request body

Key	Data type	Description of value
`items`	Object	Contains details about each of the import items. See the rows below for details.
`drs_uri`	String	DRS URI of the file that you want to import, for example `drs://caninedc.org/01349ad3-6008-426f-a17c-88dcc00492fe`
`parent`	String	The ID of the target folder to which the item should be imported, for example `568cf5dce4b0307bc0462060` Should not be used together with project. If parent is used, the import will take place into the specified folder, within the project to which the folder belongs. If project is used, the items will be imported to the root of the project's files.
`project`	String	The project in which to import the file. Should be specified in the username/project-slug format, for example `rfranklin/my-project`.
`name`	String	The name of the file when imported to the destination. If the name is already in use in the project, the rule defined in `conflict_resolution` will apply.
`metadata`	Object	Consists of key-value pairs of metadata fields that should be assigned to the imported files. Learn more
`conflict_resolution`	String	Action to take if a file with the same name already exists in the project. Available values: `OVERWRITE` `RENAME` `SKIP` Default: `SKIP`
`tags`	Array of strings	Tags that will help label and differentiate the imported files in the project. Learn more

Example request body

{
	"conflict_resolution": "SKIP",
	"items": [{
		"drs_uri": "drs://nci-crdc.datacommons.io/1805d249-bc24-4eed-b191-86d333d7563f",
		"project": "rfranklin/drs-import/",
		"name": "test-file.ext",
		"metadata": {
			"study_id": "1",
			"cohort": 4
		}
	}],
	"tags": [
		"ICDC"
	]
}

Response

See a list of CAVATICA-specific response codes that may be contained in the body of the response.

Response body

The response object contains the link for downloading the file.

Key	Data type	Description
`href`	String	URI of this import job, for example `https://cavatica-api.sbgenomics.com/v2/async/files/import/436242183587799`.
`id`	String	ID of the import job.
`result`	Array	Files and errors for each of the items in the bulk import job.
`started_on`	String	Date and time when the import job started.
`finished_on`	String	Date and time when the import job ended.
`state`	String	Current state of the import job. Available values: `SUBMITTED` `RESOLVING` `RUNNING` `FINISHED`

Example response body

{
    "href": "https://cavatica-api.sbgenomics.com/v2/bulk/drs/imports/154606575995752448",
    "id": "154606575995752448",
    "result": [],
    "state": "SUBMITTED"
}