Skip to main content

Update Data

POST 
/api/v1/assets/:asset_id/data/update

Save arbitrary JSON data as custom metadata for an asset.

Note: To add custom metadata during asset upload, see Upload API

Higher throughput with async mode​

The Update Data API synchronously updates asset data within multiple services (Database, Search). For higher throughput with eventual consistency, use the async query parameter. Supply async=1 in the API URL, e.g. /api/v1/assets/{asset_id}/data/update?async=1.

warning

When async=1 is used, Get Data and Search may take seconds to minutes to reflect metadata changes. Use async mode only if this trade-off is acceptable.

REQUEST JSON BODY​

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

Note: 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.

Important: 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"
}
KeyValueDescription
dataJSONJSON data to be saved with the file
modestringAPPEND 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
}

Request​

Responses​

Successful operation