Skip to main content

Replace Asset Content

POST 
/api/v1/assets/:asset_id/content/original/replace

API to replace the original content file of an asset while keeping the Asset ID unchanged.

Different host for uploads

This endpoint is served on https://upload.filespin.io — not the standard https://app.filespin.io host used by the rest of the API. Make sure your client targets the upload host for this request.

Note: For replacing files from within web pages, use the File Picker in Replace mode. To add or update custom metadata for the asset during replace, see Adding metadata to the asset.

Who can replace​

The asset's owner needs upload permission; anyone else needs edit access to the asset. (A user who can only view a shared asset cannot replace it.)

Formats during a replace​

The current formats stay available while the new ones are generated and are then overwritten in place; formats the new file will not produce are deleted. CDN links are refreshed when processing finishes.

With content versioning​

If the account has turned on content versioning, the replacement is stored as a version:

  • Keep history: it goes live at once and the previous file is kept as a previous version.

  • Release approval: it does not change the asset. The response carries "status": "PENDING_APPROVAL" and the version number, at the top level and on the file; the current file keeps serving until someone makes the version live. Metadata sent with the replace is applied when it goes live. Only one version can wait at a time: a second replace returns 409 with "code": "version_pending" and the waiting version's number.

    Send the optional form field needed_by (ISO 8601 date such as 2026-11-02, or a date-time; UTC when no zone is given) to say when the version is needed live. It orders the release queue and the daily summary sent to the account's release roles. An invalid value is refused with 400 before anything is stored.

{
  "files": [{"id": "99d819953914402babbdeb68337ea6a3", "name": "sample-v2.jpg", "size": 60892,
             "checksum": "cd1b78e4686ae1a3cfb461a1085545f0", "content_type": "image/jpeg",
             "status": "PENDING_APPROVAL", "version": 5}],
  "success": true,
  "provider": "local",
  "status": "PENDING_APPROVAL",
  "version": 5
}

Any change of the asset's live content fires the asset.replaced webhook.

HTTP RESPONSE​

KeyValueDescription
filesJSONList of files
idstringAsset ID, 32 character alphanumeric UUID
namestringFile name
sizeintegerSize of file in bytes
checksumstringMD5 checksum
content_typestringMIME type
providerstringalways "local" to indicate local upload
successbooleantrue if upload completed, false otherwise
metadataJSONOnly returned for custom plans. Applies to image uploads. Where available, Exiftool tag values for 'ColorMode', 'ColorSpace', 'Orientation', 'Make' and 'Model' are returned. 'Width' and 'Height' are always returned

Response JSON​

{
  "files": [
    {
      "id": "99d819953914402babbdeb68337ea6a3",
      "name": "sample.jpg",
      "size": 8836363,
      "checksum": "5f5f26bd7c0f62c6e02e44c73d09734e",
      "content_type": "image/jpeg",
      "metadata": {
        "Make": "Apple",
        "ColorSpace": "sRGB",
        "Model": "iPhone 3G",
        "Orientation": "Horizontal (normal)",
        "width": 1200,
        "height": 800
      }
    }
  ],
  "success": true,
  "provider": "local"
}

Request​

Responses​

Asset content replaced successfully