Save arbitrary JSON data as custom metadata for an asset.

📘
To add custom metadata during asset upload, see Upload API

REQUEST JSON BODY

The request body should be a JSON with data and mode keys.

📘
Add "filespin_search_txt" special key to have it's value indexed for search. This is useful if you would like to add your own ID to a file and later retrieve the file by that ID.

❗️
Ensure that custom data fields sent for update do not begin with _filespin. This is a reserved field prefix used by FileSpin to capture internal and generated data such as addon processing outputs. Data fields that begin with _filespin are not user updateable.

Example request

To update file data, send a JSON payload like below to store with the file.

{
  "data": {
    "input1": "value1",
    "input2": "value2",
    "filespin_search_txt": "MY_OWN_FILE_ID"
  },
  "mode": "APPEND"
}

Key	Value	Description
`data`	JSON	JSON data to be saved with the file
`mode`	string	`APPEND` will append the data to any existing data. `REPLACE` will overwrite with the new data

"APPEND" mode

Consider the scenario where

Asset contains this data:

"data": {
  {
   "myfield": "myvalue",
   "input1": "OLD-VALUE"
  }
}

"APPEND" mode request is sent with the below payload

{
  "data": {
    "input1": "NEW-VALUE",
    "input2": "value2"
  },
  "mode": "APPEND"
}

Asset will be updated so that the resulting asset data is as below:-

Note that any existing field value is overwritten by new value if that field is sent in payload

Final Asset Data

"data": {
 {
   "myfield": "myvalue",
   "input1": "NEW-VALUE",
   "input2": "value2"
  }
}

"REPLACE" mode

Consider the scenario where

Asset contains this data:

"data": {
  {
      "myfield": "myvalue"
  }
}

"REPLACE" mode request is sent with the below payload

{
  "data": {
    "input1": "value1",
    "input2": "value2",
    "filespin_search_txt": "MY_OWN_FILE_ID"
  },
  "mode": "REPLACE"
}

Asset will be updated so that the resulting asset data is as below:-

Final Asset Data

"data": {
 {
    "input1": "value1",
    "input2": "value2",
    "filespin_search_txt": "MY_OWN_FILE_ID"
  }
}

API Limits

Maximum payload size is limited to 2000 characters.
If Asset is in NOT_READY state (that is, asset is in-flight to Storage) this API will return HTTP 400. Check for OK status using Asset Data API before updating or retry after a few seconds.
If Asset metadata is being updated by another process, this API will return a HTTP 202 until the other update completes.

JSON Schema support

FileSpin supports JSON Schema for Asset Data. Assigning schema to asset data enables versatile field-based search and additional data validations.

Once one or more schemas have been setup for an account, you can pass the optional schema id data_schema_id as shown below to automatically assign a schema to the asset data.

{
  "data": {
    "input1": "value1",
    "input2": "value2",
    "filespin_search_txt": "MY_OWN_FILE_ID"
  },
  "mode": "APPEND",
  "data_schema_id": 1  
}

🚧
If the data JSON value does not conform to the Schema specified by data_schema_id searchable fields will not be indexed. If no schema id is supplied, Default Schema will be assigned.

Response

HTTP 200 if successful
HTTP 202 if Asset Metadata is being updated by another process at the same time) or if async query parameter is passed (see below). Updates will be serialised and applied according to the time they were received by FileSpin.
For all other cases, standard HTTP response codes will be returned. See Response Codes.

Asynchronous Update for Higher Throughput

When Update Data API is called FileSpin synchronously updates asset data within multiple services such as Database and Search. Thus update API has inherent throughput limitations due the nature of synchronous service calls.

In scenarios where there is a need for higher throughput with eventual consistency, update API can be called in asynchronous mode. The update API provides asyncquery parameter option that can be used to inform FileSpin to perform the update asynchronously. Asynchronous mode provides higher throughput while offering eventual data consistency of asset data across the system.

To use asynchronous update, supply async=1 as a query parameter in the API URL, like /api/v1/assets/{ASSET_ID}/data/update?async=1

🚧
Note that when asynchronous mode is used, FileSpin API such as Get Data and Search may take time to reflect the metadata changes. This time may range from a few seconds to minutes depending on volume of async updates. Asynchronous mode should be used only if this trade-off is acceptable.