Update file details

This call updates the name, the full set metadata, and tags for a specified file.

Files are specified by their IDs, which you can obtain by making the API call to list files in a project.

If you want to update metadata for multiple files, the recommended way is to do it in bulk considering the API rate limit (learn more).

🚧

Metadata

Learn more about metadata fields and their permissible values on the Seven Bridges Platform.

Request

https://api.sbgenomics.com/v2/files/{file_id}
https://eu-api.sbgenomics.com/v2/files/{file_id}

Example request

PATCH /v2/files/562e449060b274321afb6091 HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 565357a1e4b09c884b29334a
curl --data '{"metadata": {disease_type: "Acute Myeloid Leukemia"}} -s -H "X-SBG-Auth-Token: 6282d5e2121d43e7900e9d52b15845e7" -H "content-type: application/json" -X PATCH "https://api.sbgenomics.com/v2/files/562e449060b274321afb6091"
from sevenbridges import Api

api = Api(url='https://api.sbgenomics.com/v2',
          token='3259c50e1ac5426ea8f1273259740f74')

file = api.files.get(id='562e449060b274321afb6091')

# change file details
file.name = '1_1000Genomes_phase1.snps.high_confidence.b37.vcf'
file.metadata['disease_type'] = 'Acute Myeloid Leukemia'
file.tags = ['test 1b', 'sample']

# send PATCH request to SB API for metadata change
# send PUT request to SB API for tag change
# send PATCH request to SB API for name change
file.save()

print(file.name)

🚧

File names and IDs

Note that the file name is not the same as its ID. The ID is a hexadecimal string, automatically assigned to a file in a project. The file's name is a human-readable string. For information about identifying objects in the API, see the section on identifying objects.

Custom metadata fields

As well as the standard set of metadata fields that can be seen through the visual interface, you are also able to add custom metadata for your files. Custom metadata fields are user-defined key-value pairs that allow you to provide additional metadata associated to files on the Platform. Custom metadata can be added via the command line uploader or via the API, but not through the visual interface.

📘

Custom metadata fields will not be visible on the visual interface, but their values can be retrieved by getting file details via the API.

The following rules apply to custom metadata fields:

  • Keys and values are case sensitive unless explicitly treated differently by a tool or a part of the Platform.
  • Maximum number of key-value pairs per file is 1000, including null-value keys.
  • Keys and values are UTF-8 encoded strings.
  • Maximum length of a key is 100 bytes (UTF-8 encoding).
  • Maximum length of a value is 300 bytes (UTF-8 encoding).

Tags

You can use this API request to add a set of tags for your file. Any list of tags specified in this request will overwrite the previously set tags on the file. Learn more about tagging your files on the Platform.

In addition to editing tags on your files, you can do the following via the API:

Header Fields

Name

Description

X-SBG-Auth-Token
required

Your Seven Bridges Platform authentication token.

Path parameters

Name

Description

file_id

The ID of the file whose details you want to update.

Query parameters

Name

Data type

Description

fields

string

Selector specifying a subset of fields to include in the response.

Request body

You should enter the body as key-value pairs, with the following format:

Key

Datatype of value

Description of value

name

string

The new name of the file.

metadata

dictionary of key-value pairs. The keys and values are strings.

The metadata fields and their values that you want to update.

tags

array

The tags you want to update.

Example request body

In the example below, I have submitted a request to change the file name to "1_1000Genomes_phase1.snps.high_confidence.b37.vcf" and to have the metadata contain only the field disease_type with value "Acute Myeloid Leukemia". This request also adds the tags test 1b and sample.

{
  "name": "1_1000Genomes_phase1.snps.high_confidence.b37.vcf",
  "metadata": {
    "disease_type": "Acute Myeloid Leukemia"
    },
  "tags": ["test 1b", "sample"]
}

Response

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

Example response body

Notice that the metadata contains only the fields specified in the request body.

{
  "href": "https://api.sbgenomics.com/v2/files/562e449060b274321afb6091",
  "id": "562e449060b274321afb6091",
  "name": "1_1000Genomes_phase1.snps.high_confidence.b37.vcf",
  "size": 363,
  "project": "rfranklin/my-project",
  "created_on": "2015-12-11T11:01:49Z",
  "modified_on": "2016-01-07T12:22:12Z",
  "origin": {},
  "metadata": {
    "disease_type": "Acute Myeloid Leukemia",
  },
  "tags":[
    "test 1b",
    "sample"
  ]
}
Interpreting the response body:
  • The object origin denotes the task that produced the file, if it was created by a task on the Seven Bridges Platform.
  • The dictionary object metadata lists the metadata fields and values for the file.
  • The object tags lists the tags for the file. Learn more about tagging your files on the Platform.