> For the complete documentation index, see [llms.txt](https://docs.startrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/update-metadata.md).

# Update metadata

PUT and PATCH /commerce/srrs/{tokenId}/metadata — replace or patch the metadata document of an issued SRR; set/append/prepend/insert, baseCid, 204.

<mark style="color:orange;">`PUT`</mark> `<base_url>/port/api/v1/commerce/srrs/{tokenId}/metadata` — full replacement

<mark style="color:purple;">`PATCH`</mark> `<base_url>/port/api/v1/commerce/srrs/{tokenId}/metadata` — partial update

Both routes end the same way: the new document is validated against its schema, pinned, and `updateSRRMetadataWithCid` is sent on chain. The SRR gets a new `metadataDigest`; every previous version stays in its metadata history. An update is not a transfer: the owner does not change.

#### Headers

| Name                                               | Type   | Description                       |
| -------------------------------------------------- | ------ | --------------------------------- |
| commerce-api-key<mark style="color:red;">\*</mark> | string | Commerce API Key                  |
| issuer-address<mark style="color:red;">\*</mark>   | string | Contract Address of API Key owner |

#### Path

| Name                                      | Description                                |
| ----------------------------------------- | ------------------------------------------ |
| tokenId<mark style="color:red;">\*</mark> | Decimal token id (digits only, at most 78) |

#### Permissions

The LUW behind the API key must be the SRR's **issuer or artist**; on a collection, the **collection owner** is accepted as well. The owner of the SRR alone cannot update it. This is enforced when the typed data is built, after the document was checked.

## PUT — replace the document

| Body field                                           | Type   | Description                                                                                                                                                                                                                                  |
| ---------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId`                                          | string | Optional idempotency key, same rule as issuance                                                                                                                                                                                              |
| `payload.metadata`<mark style="color:red;">\*</mark> | object | The complete new document. `$schema` may be an official URL or a registered schema in any of the [three forms](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas.md#the-three-forms-of-the-schema-reference) |
| `payload.collectionAddress`                          | string | Required when the SRR lives on a collection; omit on the shared registry                                                                                                                                                                     |

The document stays on the schema version its `$schema` names (a registered schema is not moved to latest on update). Storage `finalUrl`s anywhere in a registered-schema document become `ipfs://<cid>`; on the official schema the file-URL rules of issuance apply.

## PATCH — change part of the document

gogh-api reads the current document, applies your changes, and continues exactly as `PUT`.

| Body field                  | Type   | Description                                                                                                                                                      |
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requestId`                 | string | Optional idempotency key                                                                                                                                         |
| `payload.set`               | object | Top-level fields to set. A value replaces the whole field (no deep merge); `null` removes it; new fields are added. Applied first. `$schema` cannot be set here. |
| `payload.append`            | object | `{ "<field>": [entries] }` — entries added at the end of a top-level array (created if absent)                                                                   |
| `payload.prepend`           | object | `{ "<field>": [entries] }` — entries put at the start, in the order given                                                                                        |
| `payload.insert`            | object | `{ "<field>": { "index": n, "entries": [entries] } }` — `index` is the position the first entry takes; `0` = prepend, current length = append                    |
| `payload.schema`            | string | Move the document to another schema version (CID or name form). Omitted = keep the current `$schema`                                                             |
| `payload.baseCid`           | string | CID of the document to patch on top of — the `metadataCID` of your previous update. Omitted = the CID the subgraph currently holds                               |
| `payload.collectionAddress` | string | Required on a collection                                                                                                                                         |

At least one of `set`, `append`, `prepend`, `insert`, `schema` must be present.

{% hint style="warning" %}
**One array operation per field per request.** `append`, `prepend` and `insert` on the same field in one request is refused, so the outcome never depends on an order between them. `set` of a field and an array operation on the same field is allowed: `set` runs first, the array operation on its result.
{% endhint %}

{% hint style="danger" %}
**`baseCid` is a pointer, not a lock.** gogh-api patches on top of the document that `baseCid` names and does **not** compare it with the CID the SRR currently has. A stale `baseCid` silently produces a document that drops every change made since, and the chain accepts it. Send **one update at a time per record**, and pass the `metadataCID` of the last response as `baseCid` when chaining — it also sidesteps the few seconds the subgraph can lag behind a transaction that was just sent.
{% endhint %}

### Which to use

| Change                                         | Use                                                   |
| ---------------------------------------------- | ----------------------------------------------------- |
| Add a history entry (newest first)             | `prepend.<field>`                                     |
| Add a history entry (oldest first)             | `append.<field>`                                      |
| Change one scalar or object field              | `set.<field>`                                         |
| Change one entry inside an array               | `set.<field>` with the whole array                    |
| Remove a field                                 | `set.<field>: null`                                   |
| Add a field the current version does not allow | `set` plus `schema` naming the version that allows it |
| Rewrite everything                             | `PUT`                                                 |

### Automatic archiving of long histories

A registered schema can mark a top-level array so that gogh-api archives its oldest entries by itself when an add would push it past `maxItems`:

```json
"beneficiaries": { "type": "array", "maxItems": 10, "x-archive": true }
"beneficiaries": { "type": "array", "maxItems": 10, "x-archive": { "keep": 5, "ref": "archivedBeneficiaries", "oldest": "last" } }
```

| Key        | Meaning                                                                                                        | Default                                     |
| ---------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `maxItems` | the trigger: a `PATCH` that leaves more entries than this archives first                                       | —                                           |
| `keep`     | entries that stay in the record after archiving, from the newest end, the ones just added included             | `1`                                         |
| `ref`      | the field that receives the archive reference                                                                  | `archived<Field>` (`archivedBeneficiaries`) |
| `oldest`   | where the oldest entries sit: `"last"` for newest-first histories (`prepend`), `"first"` for append-style logs | `"last"`                                    |

When it triggers, in the same request: the oldest entries go to an archive file on IPFS — `{ "field", "entries" (record order), "archivedAt", "previous"?: the earlier reference, "record": { "tokenId", "collectionAddress"? } }` — the record keeps the newest `keep` entries, and `ref` is set to `{ "cid", "count", "archivedAt" }` where `count` is the length of the whole chain (this file and every `previous` one). The response lists it under `archived` (`field`, `ref`, `cid`, `metadataURL`, `entries`, `count`). Readers walk the chain through `previous`.

An entry is never archived on arrival: a request that adds more entries than `keep` is refused. Official schemas, registered schemas without the keyword and patches that stay within `maxItems` are not affected; `PUT` never archives. The file is pinned before the record is validated, so a patch refused afterwards leaves an unreferenced, harmless file behind.

## Responses

{% tabs %}
{% tab title="200" %}

```json
{
  "previousMetadataCID": "bafkreidtb6ta2abip7jhdglevredpdlfmp2764u6bkwhlkjcrpruv46wla",
  "tokenId": "561308332886",
  "collectionAddress": "0x8b116a8896538377328936279e64b11303cbf7b1",
  "metadataCID": "bafkreic6dylmir5h25qds7jpqxuai5m556kdzd3jwgcf6m7m65bv32rery",
  "metadataURL": "https://cdn.startrail.io/ipfs/bafkreic6dylmir5h25qds7jpqxuai5m556kdzd3jwgcf6m7m65bv32rery",
  "txReceiptId": "12345"
}
```

| Field                 | Description                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `previousMetadataCID` | **PATCH only.** The CID the change was applied to (your `baseCid`, or what the subgraph held). |
| `tokenId`             | The SRR                                                                                        |
| `collectionAddress`   | Lower-cased collection address, `null` on the shared registry                                  |
| `metadataCID`         | CID of the new document. Pass it as `baseCid` on the next patch                                |
| `metadataURL`         | The new document on the CDN gateway                                                            |
| `txReceiptId`         | Receipt id of the on-chain transaction, when startrail-api returned one                        |
| {% endtab %}          |                                                                                                |

{% tab title="204" %}
No body. The request leaves the document exactly as it is — the new document's CID equals the current one (for `PATCH`: equals `baseCid` or the subgraph's CID). Nothing was pinned, nothing was sent, the metadata history has no new entry. Examples: a `PUT` with the current document, a `set` with the value the field already has, a document that differs only by a storage URL of a file it already holds as `ipfs://<cid>`.
{% endtab %}
{% endtabs %}

The `200` means accepted. The subgraph shows the new `metadataDigest` once the transaction is mined; see [subgraph lag](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md#edge-cases).

## Examples

{% tabs %}
{% tab title="PATCH prepend" %}

```json
{
  "requestId": "ingot-sale-2026-10-27-001",
  "payload": {
    "set": {
      "hubEventId": "c9362e9706101d532cd2139e645e762e522e0ef1d915d66737be886c5e99a60f"
    },
    "prepend": {
      "beneficiaries": [
        {
          "effectiveAt": "2026-10-14T15:00:00+02:00",
          "externalId": "48586de79f3db3d0c26c94cd53d26408f3618e1daf1767c10eaa93b802ef99e3",
          "hubEventId": "c9362e9706101d532cd2139e645e762e522e0ef1d915d66737be886c5e99a60f",
          "reason": "sale",
          "reference": "DEAL-2026-1014-04"
        }
      ]
    },
    "baseCid": "bafkreidtb6ta2abip7jhdglevredpdlfmp2764u6bkwhlkjcrpruv46wla",
    "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1"
  }
}
```

{% endtab %}

{% tab title="PATCH set" %}

```json
{
  "requestId": "ingot-custodian-2026-10-27-001",
  "payload": {
    "set": {
      "hubEventId": "e69ea5ff2a9addbcfc4f6548c6e5cc51ab277b5c159cc4b750a3d1a0f0f1f5c3",
      "custody": {
        "custodian": { "externalId": "CUST-004", "name": { "en": "Alpine Secure Storage SA" } },
        "facility": "GVA-1",
        "country": "CH",
        "since": "2026-11-10T08:00:00+01:00",
        "status": "in_custody"
      }
    },
    "baseCid": "bafkreic6dylmir5h25qds7jpqxuai5m556kdzd3jwgcf6m7m65bv32rery",
    "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1"
  }
}
```

{% endtab %}

{% tab title="PATCH insert + schema" %}

```json
{
  "payload": {
    "insert": {
      "beneficiaries": {
        "index": 1,
        "entries": [ { "effectiveAt": "2026-05-01T09:00:00+09:00", "externalId": "…", "reason": "correction" } ]
      }
    },
    "schema": "https://api.startrail.io/api/v1/schema/ingot-registry-record.v0.3.schema.json",
    "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1"
  }
}
```

{% endtab %}

{% tab title="PUT" %}

```json
{
  "requestId": "ingot-rewrite-2026-10-27-001",
  "payload": {
    "metadata": {
      "$schema": "ipfs://bafkreigxv3lhvqmfz5n6g2xzpt4ql3a4ql7ekg7kza6iz5s4ms2nrv4d4u",
      "name": "Gold bar 1 kg, serial HPM-2024-017345",
      "identifierScheme": "ingot-markings-v1",
      "itemIdentifier": "8b9e62a876ca2a6a329fb54ae575e34d11ecd2b46cb7d892a76c2d8d0c161141",
      "imageHash": "0c405ae068a7d62aef5050ab719466dab62a6a4a7458a5e16eb6ff7c30c7888c",
      "hubEventId": "0f351bf412cdef832e004a88becb048c5dae0ae1f3f3d171afbd6ade96330075"
    },
    "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1"
  }
}
```

{% endtab %}
{% endtabs %}

## Errors

Every refusal happens before anything is pinned or sent; a refused request changes nothing.

| Status | Message                                                                                                                                                                                                             | When                                                                                                                                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | `Missing header` / `API Key is not valid for <issuer-address>`                                                                                                                                                      | Headers                                                                                                                                                                                                                                                 |
| `400`  | `tokenId must be a decimal token id (got "<value>")`                                                                                                                                                                | Path param not digits                                                                                                                                                                                                                                   |
| `400`  | `payload must contain at least one of set, append, prepend, insert, schema`                                                                                                                                         | Empty `PATCH`                                                                                                                                                                                                                                           |
| `400`  | `baseCid must be the metadataCID of the document to patch on top of`                                                                                                                                                | `baseCid` is not a CID string                                                                                                                                                                                                                           |
| `400`  | `change the schema with payload.schema, not set.$schema`                                                                                                                                                            | `$schema` in `set`                                                                                                                                                                                                                                      |
| `400`  | `append.<field> must be an array` / `prepend.<field> must be an array` / `insert.<field>.entries must be an array`                                                                                                  | Entries not an array                                                                                                                                                                                                                                    |
| `400`  | `insert.<field> must be an object with index and entries`                                                                                                                                                           | Malformed `insert`                                                                                                                                                                                                                                      |
| `400`  | `insert.<field>.index must be an integer from 0 to <length>, the current length of <field>`                                                                                                                         | Index out of range                                                                                                                                                                                                                                      |
| `400`  | `<field> is the target of both <op1> and <op2>: a field takes one array operation per request`                                                                                                                      | Two array operations on one field                                                                                                                                                                                                                       |
| `400`  | `<op>.<field>: the current value of <field> is not an array`                                                                                                                                                        | Array operation on a scalar or object field                                                                                                                                                                                                             |
| `400`  | `metadata exceeds the maximum size of 204800 bytes (serialized size: <n> bytes)`                                                                                                                                    | The merged (`PATCH`) or new (`PUT`) document is too large                                                                                                                                                                                               |
| `400`  | `<field>: the request adds <n> entries but the schema keeps <keep> after archiving (x-archive); add fewer entries per request`                                                                                      | Automatic archiving would have to archive an entry this request added                                                                                                                                                                                   |
| `400`  | `the schema's x-archive on <field> is invalid: <reason>`                                                                                                                                                            | The registered schema's archiving declaration is malformed (fix the schema)                                                                                                                                                                             |
| `502`  | `schema document <cid> could not be fetched from the IPFS gateway`                                                                                                                                                  | The schema document needed for archiving is not reachable right now; retry                                                                                                                                                                              |
| `400`  | `metadata for token <tokenId> is invalid. $schema path is invalid, cid is not found (no published registry schema for ipfs://<cid>)` / `… file is not found (no published registry schema named <name> v<version>)` | Registered `$schema` (or `payload.schema`) not published                                                                                                                                                                                                |
| `400`  | `metadata for token <tokenId> is invalid. Details: <path> <message> (<params>). …`                                                                                                                                  | Official-schema document fails common-js validation                                                                                                                                                                                                     |
| `400`  | `metadata for token <tokenId> is invalid. metadata failed validation against JSON schema. Details: <path> <message> (<params>). …`                                                                                  | Registered-schema document breaks its schema (pinned form) — e.g. a `set` field the current version does not allow                                                                                                                                      |
| `400`  | `… Details: refers to a file that is not in storage ({"url":"<url>"}).` / `… refers to a file whose CID is not calculated yet, retry shortly ({"url":"<url>"}).`                                                    | Storage URL problems                                                                                                                                                                                                                                    |
| `400`  | File URL messages of the official schema — see [Errors & Troubleshooting](https://docs.startrail.io/issue-transfer-api/issue-and-transfer-srr-nft/errors.md#request-level-errors-400)                               | Official schema only                                                                                                                                                                                                                                    |
| `400`  | `Duplicate Request Error: Same requestId already logged`                                                                                                                                                            | `requestId` reused                                                                                                                                                                                                                                      |
| `400`  | `Request Content Error: Current request already logged with status in_progress` / `successful`                                                                                                                      | Same body for the same token already running or done                                                                                                                                                                                                    |
| `403`  | `Licensed user <issuer-address> is not enabled for registered metadata schemas`                                                                                                                                     | Closed release                                                                                                                                                                                                                                          |
| `404`  | `SRR <tokenId> not found or has no metadata` / `SRR <tokenId> on <collectionAddress> not found or has no metadata`                                                                                                  | Unknown token, wrong or missing `collectionAddress`, or not indexed yet                                                                                                                                                                                 |
| `404`  | `no metadata document for <cid>: <reason>`                                                                                                                                                                          | `baseCid` is a well-formed CID that nothing resolves                                                                                                                                                                                                    |
| `4xx`  | `<message>` passed through                                                                                                                                                                                          | startrail-api refused the update (permissions, token on its side) — see [the catalogue](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/errors-limits-and-edge-cases.md#put-and-patch-commerce-srrs-tokenid-metadata) |
| `500`  | `STARTRAIL_ERROR: <reason>` / `schema registry resolution failed` / `<startrail-api message>`                                                                                                                       | Signing, transport, registry or startrail-api failure                                                                                                                                                                                                   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/update-metadata.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
