Modify a file's metadata

This call modifies the metadata values for the specified file.

🚧

Metadata on the Platform

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

Request

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

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

👍

PUT and PATCH

The API has two method to modify file metadata. This method uses the HTTP verb PATCH, and the other uses the HTTP verb PUT.

  • The difference between the two concerns the way that they update the information stored about the file. PATCH allows you to update just one metadata field. On the other hand, a PUT request will fully overwrite the values for all metadata fields. This means that when issuing a PUT request you must enter values for every key required to specify the metadata, even if the values for some keys are unchanged. If you don't specify a value for a given metadata field when making the PUT request, then any existing value for that field will be reset.

Custom metadata fields

Apart from 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.

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.
  • 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).
  • Null values and keys are ignored and not counted towards the 1000 key-value pair limit.

Example request

PATCH /v2/files/562e449060b274321afb6091/metadata HTTP/1.1
Host: api.sbgenomics.com
X-SBG-Auth-Token: 565357a1e4b09c884b29334a
curl --data '{"foo": "bar"}'  -s -H "X-SBG-Auth-Token: 7942f56901534434a054dafc3813bc96" -H "content-type: application/json" -X PATCH "https://api.sbgenomics.com/v2/files/5657152ee4b0298dd2cdf724/metadata"
from sevenbridges import Api

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

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

# modify metadata
file.metadata['library_id'] = '12345'
file.metadata['platform'] = 'my_platform'
file.metadata['sample origin'] = '712345'
file.metadata['foo'] = 'bar'
file.metadata['my_key_1'] = 'my_value_1'
file.metadata['my_key_2'] = 'my_value_2'

# send PATCH request to SB API
file.save()

print(file.metadata)

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 metadata 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

Enter a dictionary of key-value pairs to the request body.

Key

Datatype of value

Description of value

Freeform -- enter any key.

string

The value for the corresponding key

Example request body

{
  "sample_id": "712345"
}

Response

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

Example response body

The response contains the full metadata specification for the file, including the values that you just added with the request.
{
  "library_id": "12345",
  "platform": "my_platform",
  "sample_id": "712345",
  "foo": "bar",
  "my_key_1": "my_value_1",
  "my_key_2": "my_value_2"
}