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"
  }
}

Adding or removing list values (list_ops)​

APPEND replaces a list field as a whole, so sending "tags": ["outdoor"] drops every other tag. To add or remove individual values, send list_ops instead. FileSpin applies them to the field's current value while it holds the asset's update lock, so a concurrent edit is never lost — there is no need to read the asset, merge the list yourself and write it back.

{
  "mode": "APPEND",
  "list_ops": {
    "tags": {"add": ["outdoor"], "remove": ["draft"]}
  }
}
  • add appends values not already in the list, in the order given. remove drops every occurrence of the given values. Either may be omitted.
  • A missing, null or empty-string field is treated as an empty list. A field holding any other non-list value returns HTTP 400 — send it in data to overwrite it.
  • data is optional when list_ops is sent, and can be combined with it, but the same field cannot appear in both.
  • list_ops is only supported with APPEND mode.
  • Values are compared by their JSON content, so 1 and "1" are different values and objects match regardless of key order.
  • When the asset has a schema, the resulting list is validated against it.
  • Limits: at most 100 fields per request and 1000 values per add or remove.

The response includes the resulting list for every field in list_ops:

{
  "status": "OK",
  "message": "Asset Data updated",
  "list_ops_applied": {"tags": ["sample", "outdoor"]}
}

Note: Check that list_ops_applied is present in the response. Servers released before list ops support ignore the list_ops key; omitting data from a list-ops-only request makes such a server return HTTP 400 instead of silently applying nothing.

Deleting fields (remove_keys)​

APPEND can only add or overwrite fields. To delete fields, send their names in remove_keys. FileSpin deletes them while it holds the asset's update lock, in the same update as any data or list_ops in the request. Other fields are left as they are.

{
  "mode": "APPEND",
  "remove_keys": ["source", "channel"]
}

Use this rather than writing "" over a field: if the asset's schema makes the field an enum, a date, a number or a boolean, an empty string fails validation and the whole update is rejected.

  • A field the asset doesn't have is skipped, so the same request is safe to retry.
  • data is optional when remove_keys is sent, and both can be combined with list_ops in one request, but a field can appear in only one of data, list_ops and remove_keys.
  • remove_keys is only supported with APPEND mode.
  • Reserved _filespin fields cannot be removed, except user-editable ones such as _filespin_autotag_labels.
  • Limit: at most 100 fields per request.

The response lists the fields that existed and are now deleted:

{
  "status": "OK",
  "message": "Asset Data updated",
  "removed_keys": ["source"]
}

Note: Check that removed_keys is present in the response. Servers released before field deletion support ignore the remove_keys key and return HTTP 200 without deleting anything; omitting data makes such a server return HTTP 400 instead.

"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 request and the update cannot start within 2 seconds, this API returns HTTP 409 and nothing is written. Retry the request.

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