---
title: "Replace a file"
description: "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."
url: https://docs.filemonk.io/v2/api-reference/assets/replace-a-file/
api: "API v2 reference"
method: POST
path: "/assets/{id}/replace"
---

# Replace a file

`POST https://app.filemonk.io/api/v2/external/assets/{id}/replace`

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.

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

## Path parameters

- `id` (string, required)

## Request body

- `filename` (string, required): e.g. `guide-v2.pdf`
- `byte_size` (integer, required): e.g. `2097152`
- `content_type` (string): e.g. `application/pdf`

## Returns

- `id` (string, nullable, required): e.g. `e2b7727e-45ad-42b7-b842-cc4615205b10`
- `type` (string, nullable, required): e.g. `file`
- `name` (string, nullable, required): e.g. `guide.pdf`
- `filename` (string, nullable, required): e.g. `guide.pdf`
- `extension` (string, nullable, required): e.g. `pdf`
- `content_type` (string, nullable, required): e.g. `application/pdf`
- `byte_size` (integer, nullable, required): e.g. `1048576`
- `url` (any, required)
- `url_expires_at` (any, required)
- `watermark` (object, required)
  - `enabled` (boolean, nullable, required): e.g. `true`
- `licence_keys` (object, required)
  - `autogenerate` (boolean, nullable, required): e.g. `false`
  - `tags` (array of anys, required)
- `usage` (object, required)
  - `digital_products_count` (integer, nullable, required): e.g. `0`
  - `orders_count` (integer, nullable, required): e.g. `0`
- `digital_products` (array of anys, required)
- `recent_orders` (array of anys, required)
- `created_at` (string, nullable, required): e.g. `2026-10-30T16:49:38Z`
- `updated_at` (string, nullable, required): e.g. `2026-10-30T16:49:38Z`
- `upload` (object, required)
  - `url` (string, nullable, required): e.g. `https://files.filemonk.io/uploads/5f3e9c1a/guide.pdf?X-Am…`
  - `method` (string, nullable, required): e.g. `PUT`
  - `headers` (object, required)
    - `Content-Type` (string, nullable, required): e.g. `application/pdf`
  - `expires_at` (string, nullable, required): e.g. `2026-10-31T00:10:00Z`

Rate limit: this call costs 2 points ([rate limits](https://docs.filemonk.io/v2/errors-and-rate-limits/)).

## Example request

```sh
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"
  }'
```

## 200

Success: the write completed; the body is the updated resource.

```json
{
  "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"
  }
}
```

## 401

Missing or invalid API key.

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

## 404

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

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

## 422

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

```json
{
  "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"
    ]
  }
}
```

## 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.

```json
{
  "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)."
}
```