---
title: "Updates a file's name, title, description and security level."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

Path: Sherpo merchant API › file

`PATCH /v1/stores/{store}/assets/{asset}`

## Authentication

- `bearer`, http, header `Authorization`, scopes: `file:write`

## Path parameters

- `store` (`updateAsset.path.store`; string, required) — The store's id.
- `asset` (`updateAsset.path.asset`; string, required)
  - minLength 1

## Header parameters

- `Idempotency-Key` (`updateAsset.header.Idempotency-Key`; string, optional) — Repeats within 24 hours answer the first result; the same key with other arguments is a conflict.
  - minLength 1; maxLength 255; pattern `^[\x21-\x7E]+$`

## Request body

_Optional._

- `attachment` (`updateAsset.attachment`; object, optional) — The binding the caller saw holding the file; one holding another refuses.
  - `id` (`updateAsset.attachment.id`; string, required)
    - minLength 1; maxLength 512
- `locator` (`updateAsset.locator`; string, optional) — A link's URL; only a link held elsewhere takes one.
  - minLength 1; maxLength 100000
- `security` (`updateAsset.security`; any of, optional) — The protection a stored PDF or spreadsheet is delivered with, refused for one no mark can be written into; null takes it off.
  - any of: `string`, `null`
- `name` (`updateAsset.name`; string, optional)
  - minLength 1; maxLength 200; pattern `^[a-z0-9][a-z0-9-]*$`
- `title` (`updateAsset.title`; any of, optional)
  - any of: `string`, `null`
- `description` (`updateAsset.description`; any of, optional)
  - any of: `string`, `null`
- `metadata` (`updateAsset.metadata`; object, optional)
  - `transcript` (`updateAsset.metadata.transcript`; object, optional)
    - `language` (`updateAsset.metadata.transcript.language`; string, optional)
      - minLength 1; maxLength 35
- `enforcement` (`updateAsset.enforcement`; string, optional) — How the file is served: `public` to anyone with its link, `signed` (a stored file's default) only through links that expire, `external` for a link held elsewhere (a link's default).
  - one of `"public"`, `"external"`, `"signed"`
- `mime` (`updateAsset.mime`; any of, optional) — A link's type; a stored file's is the one it was stored with.
  - any of: `string`, `null`
- `ext` (`updateAsset.ext`; any of, optional)
  - any of: `string`, `null`
- `redacted` (`updateAsset.redacted`; boolean, optional)

## Example request

```json
{
  "attachment": {
    "id": "string"
  },
  "locator": "string",
  "security": "basic",
  "name": "string",
  "title": "string",
  "description": "string",
  "metadata": {
    "transcript": {
      "language": "string"
    },
    "property1": true,
    "property2": true
  },
  "enforcement": "public",
  "mime": "string",
  "ext": "string",
  "redacted": true
}
```

## Code samples

### cURL

```bash
curl --request PATCH \
  --url 'https://api.sherpo.io/merchant/v1/stores/<store>/assets/<asset>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "attachment": {
    "id": "string"
  },
  "locator": "string",
  "security": "basic",
  "name": "string",
  "title": "string",
  "description": "string",
  "metadata": {
    "transcript": {
      "language": "string"
    },
    "property1": true,
    "property2": true
  },
  "enforcement": "public",
  "mime": "string",
  "ext": "string",
  "redacted": true
}
'
```

### TypeScript

```typescript
const url = 'https://api.sherpo.io/merchant/v1/stores/<store>/assets/<asset>';
const options = {
  method: 'PATCH',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    attachment: {id: 'string'},
    locator: 'string',
    security: 'basic',
    name: 'string',
    title: 'string',
    description: 'string',
    metadata: {transcript: {language: 'string'}, property1: true, property2: true},
    enforcement: 'public',
    mime: 'string',
    ext: 'string',
    redacted: true
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.sherpo.io/merchant/v1/stores/<store>/assets/<asset>"

payload = {
    "attachment": { "id": "string" },
    "locator": "string",
    "security": "basic",
    "name": "string",
    "title": "string",
    "description": "string",
    "metadata": {
        "transcript": { "language": "string" },
        "property1": True,
        "property2": True
    },
    "enforcement": "public",
    "mime": "string",
    "ext": "string",
    "redacted": True
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Updates a file's name, title, description and security level.

#### Example

```json
{
  "transforms": [
    {
      "stage": "string",
      "params": {
        "level": "string",
        "property1": true,
        "property2": true
      },
      "position": 0
    }
  ],
  "deliveries": {
    "items": [
      {
        "id": "string",
        "asset_id": "string",
        "customer_id": "string",
        "member_id": "string",
        "intent": "string",
        "channel": "string",
        "issued_at": "string",
        "expires_at": "string",
        "revoked_at": "string",
        "max_uses": 0,
        "used_count": 0,
        "used_at": "string",
        "state": "string"
      }
    ],
    "total": 0
  },
  "uses": {
    "items": [
      {
        "attachment_id": "string",
        "asset_id": "string",
        "role": "string",
        "delivery": "string",
        "target": {
          "kind": "string",
          "id": "string"
        },
        "from_body": true,
        "detachable": true,
        "release": {
          "id": "string",
          "version": "string",
          "current": true,
          "after": {
            "id": "string",
            "version": "string"
          }
        }
      }
    ],
    "total": 0,
    "detachable": 0
  },
  "children": {
    "items": [
      "string"
    ],
    "total": 0
  },
  "id": "string",
  "locator": "string",
  "origin": "string",
  "custodian": "string",
  "enforcement": "string",
  "mime": "string",
  "bytes": 0,
  "quota_bytes": 0,
  "name": "string",
  "title": "string",
  "ext": "string",
  "status": "string",
  "optimized": true,
  "parent_id": "string",
  "redacted": true,
  "security": "string",
  "description": "string",
  "processed_at": "string",
  "metadata": {
    "width": 0,
    "height": 0,
    "duration": 0,
    "pages": 0,
    "waveform": "string",
    "transcript": {
      "language": "string",
      "confidence": 0
    },
    "arguments": [
      {
        "name": "string",
        "description": "string",
        "required": true,
        "default": "string",
        "match": "string",
        "flags": "string",
        "message": "string",
        "lenient": true
      }
    ],
    "property1": true,
    "property2": true
  },
  "created_at": "string"
}
```

- `transforms` (`updateAsset.response.200.transforms`; array<object>, required)
  - `stage` (`updateAsset.response.200.transforms.stage`; string, required)
  - `params` (`updateAsset.response.200.transforms.params`; object, required)
    - `level` (`updateAsset.response.200.transforms.params.level`; string, optional)
  - `position` (`updateAsset.response.200.transforms.position`; number, required)
- `deliveries` (`updateAsset.response.200.deliveries`; object, required)
  - `items` (`updateAsset.response.200.deliveries.items`; array<object>, required)
    - `id` (`updateAsset.response.200.deliveries.items.id`; string, required)
    - `asset_id` (`updateAsset.response.200.deliveries.items.asset_id`; string, required)
    - `customer_id` (`updateAsset.response.200.deliveries.items.customer_id`; any of, required)
      - any of: `string`, `null`
    - `member_id` (`updateAsset.response.200.deliveries.items.member_id`; any of, required)
      - any of: `string`, `null`
    - `intent` (`updateAsset.response.200.deliveries.items.intent`; string, required)
    - `channel` (`updateAsset.response.200.deliveries.items.channel`; string, required)
    - `issued_at` (`updateAsset.response.200.deliveries.items.issued_at`; any of, required)
      - any of: `string`, `null`
    - `expires_at` (`updateAsset.response.200.deliveries.items.expires_at`; any of, required)
      - any of: `string`, `null`
    - `revoked_at` (`updateAsset.response.200.deliveries.items.revoked_at`; any of, required)
      - any of: `string`, `null`
    - `max_uses` (`updateAsset.response.200.deliveries.items.max_uses`; any of, required)
      - any of: `number`, `null`
    - `used_count` (`updateAsset.response.200.deliveries.items.used_count`; number, required)
    - `used_at` (`updateAsset.response.200.deliveries.items.used_at`; any of, required)
      - any of: `string`, `null`
    - `state` (`updateAsset.response.200.deliveries.items.state`; string, required)
  - `total` (`updateAsset.response.200.deliveries.total`; number, required)
- `uses` (`updateAsset.response.200.uses`; object, required)
  - `items` (`updateAsset.response.200.uses.items`; array<object>, required)
    - `attachment_id` (`updateAsset.response.200.uses.items.attachment_id`; string, required)
    - `asset_id` (`updateAsset.response.200.uses.items.asset_id`; string, required)
    - `role` (`updateAsset.response.200.uses.items.role`; string, required)
    - `delivery` (`updateAsset.response.200.uses.items.delivery`; string, required)
    - `target` (`updateAsset.response.200.uses.items.target`; object, required)
      - `kind` (`updateAsset.response.200.uses.items.target.kind`; string, required)
      - `id` (`updateAsset.response.200.uses.items.target.id`; string, required)
    - `from_body` (`updateAsset.response.200.uses.items.from_body`; boolean, required)
    - `detachable` (`updateAsset.response.200.uses.items.detachable`; boolean, required)
    - `release` (`updateAsset.response.200.uses.items.release`; any of, required) — The software release shipping it, whether it is the current download, and the release holders download once it goes; null for a file no release ships.
      - any of: `object`, `null`
  - `total` (`updateAsset.response.200.uses.total`; number, required)
  - `detachable` (`updateAsset.response.200.uses.detachable`; number, required)
- `children` (`updateAsset.response.200.children`; object, required)
  - `items` (`updateAsset.response.200.children.items`; array<string>, required)
  - `total` (`updateAsset.response.200.children.total`; number, required)
- `id` (`updateAsset.response.200.id`; string, required)
- `locator` (`updateAsset.response.200.locator`; any of, required)
  - any of: `string`, `null`
- `origin` (`updateAsset.response.200.origin`; string, required)
- `custodian` (`updateAsset.response.200.custodian`; string, required)
- `enforcement` (`updateAsset.response.200.enforcement`; string, required)
- `mime` (`updateAsset.response.200.mime`; any of, required)
  - any of: `string`, `null`
- `bytes` (`updateAsset.response.200.bytes`; any of, required) — The file's size in bytes; null when it is charged nothing.
  - any of: `number`, `null`
- `quota_bytes` (`updateAsset.response.200.quota_bytes`; number, required) — The file's size in bytes; zero when it is charged nothing.
- `name` (`updateAsset.response.200.name`; string, required)
- `title` (`updateAsset.response.200.title`; any of, required)
  - any of: `string`, `null`
- `ext` (`updateAsset.response.200.ext`; any of, required)
  - any of: `string`, `null`
- `status` (`updateAsset.response.200.status`; string, required)
- `optimized` (`updateAsset.response.200.optimized`; boolean, required)
- `parent_id` (`updateAsset.response.200.parent_id`; any of, required)
  - any of: `string`, `null`
- `redacted` (`updateAsset.response.200.redacted`; boolean, required)
- `security` (`updateAsset.response.200.security`; any of, required)
  - any of: `string`, `null`
- `description` (`updateAsset.response.200.description`; any of, required)
  - any of: `string`, `null`
- `processed_at` (`updateAsset.response.200.processed_at`; any of, required)
  - any of: `string`, `null`
- `metadata` (`updateAsset.response.200.metadata`; object, required)
  - `width` (`updateAsset.response.200.metadata.width`; integer, optional)
    - min 0
  - `height` (`updateAsset.response.200.metadata.height`; integer, optional)
    - min 0
  - `duration` (`updateAsset.response.200.metadata.duration`; number, optional) — Seconds, measured, so rarely whole.
  - `pages` (`updateAsset.response.200.metadata.pages`; integer, optional)
    - min 0
  - `waveform` (`updateAsset.response.200.metadata.waveform`; any of, optional) — An audio file's waveform: 256 levels from 0 to 255, base64; null when it can't be drawn.
    - any of: `string`, `null`
  - `transcript` (`updateAsset.response.200.metadata.transcript`; object, optional)
    - `language` (`updateAsset.response.200.metadata.transcript.language`; string, optional)
    - `confidence` (`updateAsset.response.200.metadata.transcript.confidence`; number, optional)
  - `arguments` (`updateAsset.response.200.metadata.arguments`; array<object>, optional) — What an MCP prompt asks for; only an authored prompt carries it.
    - `name` (`updateAsset.response.200.metadata.arguments.name`; string, required)
    - `description` (`updateAsset.response.200.metadata.arguments.description`; any of, required)
      - any of: `string`, `null`
    - `required` (`updateAsset.response.200.metadata.arguments.required`; boolean, required)
    - `default` (`updateAsset.response.200.metadata.arguments.default`; any of, required)
      - any of: `string`, `null`
    - `match` (`updateAsset.response.200.metadata.arguments.match`; any of, required) — Pattern the whole value must match, diacritic-insensitive.
      - any of: `string`, `null`
    - `flags` (`updateAsset.response.200.metadata.arguments.flags`; any of, required) — Flags among `i`, `s` and `u` the pattern runs with; null for `i` alone.
      - any of: `string`, `null`
    - `message` (`updateAsset.response.200.metadata.arguments.message`; any of, required) — What a refused value is told instead of the default reason.
      - any of: `string`, `null`
    - `lenient` (`updateAsset.response.200.metadata.arguments.lenient`; boolean, required)
- `created_at` (`updateAsset.response.200.created_at`; any of, required)
  - any of: `string`, `null`

### default

A problem; see https://api.sherpo.io/merchant/docs/errors.

#### Example

```json
{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "string",
  "context": {},
  "reached_core": true,
  "core_answer": "string"
}
```

- `type` (`updateAsset.response.default.type`; string, required)
  - format `uri`
- `title` (`updateAsset.response.default.title`; string, required)
- `status` (`updateAsset.response.default.status`; integer, required)
- `detail` (`updateAsset.response.default.detail`; string, required)
- `code` (`updateAsset.response.default.code`; string, optional)
- `context` (`updateAsset.response.default.context`; object, optional)
- `reached_core` (`updateAsset.response.default.reached_core`; boolean, optional)
- `core_answer` (`updateAsset.response.default.core_answer`; string, optional)


Source: https://docs.sherpo.io/merchant-api/reference/update-asset/index.md
