API calls related to file objects:
Retrieve
Return a single file
GET /api/v1/vaults/<vault_id>/files/<file_id>
- Note: The contents are base64 encoded
Example
curl -H "X-CDD-Token: $TOKEN" -X GET "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files/<file_id>"
Returns:
N.B. "mime_type" returns fields "hash" and "symbol". These are internal fields for the mime type objects in Rails and should be ignored. The fields "string" and "synonyms" can be used as full mime types of the file.
{
"id": 1069448031,
"class": "uploaded file",
"name": "tmp.txt",
"mime_type":
{
"synonyms": [],
"symbol": "text",
"string": "text/plain",
"hash": -1147906696977776415
},
"character_set": "US-ASCII",
"contents": "VGhpcyBpcyBhIGZpbGUK"
}Following this up with:
echo VGhpcyBpcyBhIGZpbGUK | base64 -D
Returns:
This is a file- Note: "This is a file" is the actual content of this text file
Create
Attach a file to an object (Run, Molecule, Protocol or ELN entry)
POST /api/v1/vaults/<vault_id>/files
Example (adding a file to a Protocol Run)
curl -H "X-CDD-Token: $TOKEN" -X POST --form "file=@C:\files\<file_name>" --form "resource_class=run" --form "resource_id=<run_id>" "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files"
Returns:
{
"id": "1069448044"
"name": "<file_name>"
}- Note: Additional allowed values for resource_class are "molecule", "protocol" and "eln_entry".
Example (adding a file to an ELN Entry)
curl -H "X-CDD-Token: $TOKEN" -X POST --form "file=@C:\files\<file_name>" --form "resource_class=eln_entry" --form "resource_id=<eln_entry_id>" "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files"
Returns:
{
"id": "7395612976"
"name": "<file_name>"
}- Note: To add a file into an ELN entry, the entry must already exist. ELN Entries can be created (by Vault Administrators only) using the POST eln/entries API call.
Attach a file to a Molecule/Batch field or a Protocol Readout Row
There is a 2-step API workflow available now to programmatically attach files to Molecule/Batch fields and to Protocol readouts.
The first step involves using the POST Files API end point to send a file to the CDD Vault server. This step returns an internal file id that must be used in a 2nd API call to attach this file to the desired field/readout.
Step 1
The 1st API call used is POST /api/v1/vaults/<vault_id>/files which returns JSON containing the internal file id.
{
"id": 20167608,
"name": "FlowCyto.png",
"expires_at": "2023-10-13"
}
Helpful Hint: The JSON also includes an “expires_at” date indicating when the file you just sent to the CDD Vault server will no longer exist if it’s not subsequently attached to a field/readout.
Step 2
The next API call should attach the file to the desired field/readout. This step uses the PUT Molecules, PUT Batches or PUT Readout_Rows end points.
PUT /api/v1/vaults/<vault_id>/molecules
PUT /api/v1/vaults/<vault_id>/batches
PUT /api/v1/vaults/<vault_id>/readout_rows
Example (adding a file to a Batch field)
As an example, if the file just POSTed needs to be attached to an existing Batch field, use this API call:
PUT https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/batches/<batch_id>And pass JSON like this:
{"batch_fields":
{"DataFile": 20167608}
}
Example (adding a file to an existing Readout Row)
As another example, if the file just POSTed needs to be attached to an existing Protocol readout row, use this API call:
PUT https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/readout_rows/<readout_row_id>And pass JSON like this:
{"readouts":
{"1146750": {"value": "20167608"}}
}
Delete
Delete a file attachment
DELETE /api/v1/vaults/<vault_id>/files/<file_id>
Deletes a single file.
- Note: This action is only possible for files with "class": "data file" which are not actively being imported and do not have committed data associated with them.
Example
curl -H "X-CDD-Token: $TOKEN" -X DELETE "https://app.collaborativedrug.com/api/v1/vaults/<vault_id>/files/<file_id>"
Returns:
{
"message": "File with ID <file_id> has been destroyed"
}