Replace a file

POST/assets/{id}/replace

Costs 2 rate-limit points · Rate limits

Swap the stored body of a file for a new version, keeping its id, products and orders, as the Files page's Replace does. Answers with upload: {url, method, headers, expires_at}; PUT the new body there within the hour.

Stored files only (type file). Every watermarked copy is invalidated and re-stamped on next download.

Also searched asreplace fileupload a new versionswap the fileupdate the pdf

Path parameters

idstringRequired

Request body

filenamestringRequired
Example: guide-v2.pdf
byte_sizeintegerRequired
Example: 2097152
content_typestring
Example: application/pdf

Returns

idstring, nullable
Example: e2b7727e-45ad-42b7-b842-cc4615205b10
typestring, nullable
Example: file
namestring, nullable
Example: guide.pdf
filenamestring, nullable
Example: guide.pdf
extensionstring, nullable
Example: pdf
content_typestring, nullable
Example: application/pdf
byte_sizeinteger, nullable
Example: 1048576
urlany
url_expires_atany
watermarkobject
Show 1 child attributeHide child attributes
- enabledboolean, nullable
  Example: true
licence_keysobject
Show 2 child attributesHide child attributes
- autogenerateboolean, nullable
  Example: false
- tagsarray of anys
usageobject
Show 2 child attributesHide child attributes
- digital_products_countinteger, nullable
  Example: 0
- orders_countinteger, nullable
  Example: 0
digital_productsarray of anys
recent_ordersarray of anys
created_atstring, nullable
Example: 2026-10-30T16:49:38Z
updated_atstring, nullable
Example: 2026-10-30T16:49:38Z
uploadobject
Show 4 child attributesHide child attributes
- urlstring, nullable
  Example: https://files.filemonk.io/uploads/5f3e9c1a/guide.pdf?X-Am…
- methodstring, nullable
  Example: PUT
- headersobject
  Show 1 child attributeHide child attributes
  - Content-Typestring, nullable
    Example: application/pdf
- expires_atstring, nullable
  Example: 2026-10-31T00:10:00Z

Errors

401

Missing or invalid API key.

404

The resource does not exist for this shop, or the action path is not registered.

422

The request failed validation, or sent a key the action does not take (code: "unknown_parameters" with unknown and accepted). Nothing was saved.

429

Rate limited. Cost-weighted per API key, shared with API v1: a read costs 1 point, a write 2, 40 points per fixed 60-second window. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time the window ends); a 429 adds Retry-After (seconds), retry_after, retryable: true and a next_step in the body. A 429 did nothing: wait retry_after seconds, then send the same request again. The budget is per key, so every tool or script using the key shares it; prefer one list call with per_page over many single reads.

Every error has the same shape: see Errors.

POST/assets/{id}/replace

curl -X POST "https://app.filemonk.io/api/v2/external/assets/e2b7727e-45ad-42b7-b842-cc4615205b10/replace" \
  -H "X-Auth-Token: $FILEMONK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "guide-v2.pdf",
    "byte_size": 2097152,
    "content_type": "application/pdf"
  }'

const res = await fetch("https://app.filemonk.io/api/v2/external/assets/e2b7727e-45ad-42b7-b842-cc4615205b10/replace", {
  method: "POST",
  headers: {
    "X-Auth-Token": process.env.FILEMONK_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "filename": "guide-v2.pdf",
    "byte_size": 2097152,
    "content_type": "application/pdf"
  }),
});
const data = await res.json();

import os
import requests

res = requests.post(
    "https://app.filemonk.io/api/v2/external/assets/e2b7727e-45ad-42b7-b842-cc4615205b10/replace",
    headers={"X-Auth-Token": os.environ["FILEMONK_API_KEY"]},
    json={
        "filename": "guide-v2.pdf",
        "byte_size": 2097152,
        "content_type": "application/pdf"
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.filemonk.io/api/v2/external/assets/e2b7727e-45ad-42b7-b842-cc4615205b10/replace")
req = Net::HTTP::Post.new(uri, "X-Auth-Token" => ENV["FILEMONK_API_KEY"], "Content-Type" => "application/json")
req.body = {
  filename: "guide-v2.pdf",
  byte_size: 2097152,
  content_type: "application/pdf"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Response

{
  "id": "e2b7727e-45ad-42b7-b842-cc4615205b10",
  "type": "file",
  "name": "guide.pdf",
  "filename": "guide.pdf",
  "extension": "pdf",
  "content_type": "application/pdf",
  "byte_size": 1048576,
  "url": null,
  "url_expires_at": null,
  "watermark": {
    "enabled": true
  },
  "licence_keys": {
    "autogenerate": false,
    "tags": []
  },
  "usage": {
    "digital_products_count": 0,
    "orders_count": 0
  },
  "digital_products": [],
  "recent_orders": [],
  "created_at": "2026-10-30T16:49:38Z",
  "updated_at": "2026-10-30T16:49:38Z",
  "upload": {
    "url": "https://files.filemonk.io/uploads/5f3e9c1a/guide.pdf?X-Amz-Expires=3600&X-Amz-Signature=3f6c…",
    "method": "PUT",
    "headers": {
      "Content-Type": "application/pdf"
    },
    "expires_at": "2026-10-31T00:10:00Z"
  }
}

{
  "errors": [
    "Invalid API key"
  ]
}

{
  "errors": [
    "Order not found: c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
  ]
}

{
  "errors": [
    "access.download_limit_count must be an integer of at least 0"
  ],
  "field_errors": {
    "access.download_limit_count": [
      "must be an integer of at least 0"
    ]
  }
}

{
  "errors": [
    "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)."
  ],
  "code": "rate_limited",
  "retry_after": 12,
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 12 second(s)."
}