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

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

Request body

KeyData typeDescription of value
itemsObjectContains details about each of the import items. See the rows below for details.
drs_uriStringDRS URI of the file that you want to import, for example drs://caninedc.org/01349ad3-6008-426f-a17c-88dcc00492fe
parentStringThe 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.
projectStringThe project in which to import the file. Should be specified in the username/project-slug format, for example rfranklin/my-project.
nameStringThe 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.
metadataObjectConsists of key-value pairs of metadata fields that should be assigned to the imported files. Learn more
conflict_resolutionStringAction to take if a file with the same name already exists in the project.
Available values:
OVERWRITE
RENAME
* SKIP

Default: SKIP
tagsArray of stringsTags 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.

KeyData typeDescription
hrefStringURI of this import job, for example https://cavatica-api.sbgenomics.com/v2/async/files/import/436242183587799.
idStringID of the import job.
resultArrayFiles and errors for each of the items in the bulk import job.
started_onStringDate and time when the import job started.
finished_onStringDate and time when the import job ended.
stateStringCurrent 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"
}