> 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/pin-metadata.md).

# Pin metadata

POST /commerce/metadata — canonicalize a metadata document, pin it to IPFS and get the CID an issuance would produce.

<mark style="color:green;">`POST`</mark> `<base_url>/port/api/v1/commerce/metadata`

Pins a metadata document to IPFS and returns its CID. Nothing goes on chain and no SRR is touched. Use it to know the `metadataCID` an issuance will produce, to pin a document you will reference from another one (an archive of old history entries, for example), or to validate a document before issuing.

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

No `requestId`: the route is not logged for idempotency. Pinning the same document twice returns the same CID.

#### Request Body

| Name                                       | Type   | Description                                                        |
| ------------------------------------------ | ------ | ------------------------------------------------------------------ |
| metadata<mark style="color:red;">\*</mark> | object | The document to pin. At most 204800 bytes serialized (UTF-8 JSON). |

## What is pinned

| `metadata.$schema`                         | What happens                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Registered schema (CID or name form)       | The document is brought into the form an issuance pins: moved to the **latest published version**, `$schema` as `ipfs://<cid>`, storage `finalUrl`s as `ipfs://<cid>`. It is validated in that form; a violation is `400`. The returned CID is the `metadataCID` that `POST /commerce/srrs` would return for the same document. |
| Official schema URL, or any other value    | Pinned as supplied, canonicalized (key order), **without validation**                                                                                                                                                                                                                                                           |
| Registered reference that is not published | `400`                                                                                                                                                                                                                                                                                                                           |

The document need not be SRR metadata at all: an arbitrary JSON object without a registered `$schema` is pinned as it is.

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

```json
{
  "metadata": {
    "field": "beneficiaries",
    "entries": [
      {
        "effectiveAt": "2026-03-01T09:00:00+09:00",
        "externalId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa09",
        "reason": "sale",
        "reference": "DEAL-1001"
      }
    ],
    "archivedAt": "2026-10-23T10:00:00+09:00",
    "record": {
      "collectionAddress": "0x8B116A8896538377328936279E64B11303cBf7B1",
      "tokenId": "561308332886"
    }
  }
}
```

{% endtab %}

{% tab title="201" %}

```json
{
  "cid": "bafkreiabepvyxyetkcb3xbjo3ocuyfo6psv3rc3yj34hequwcsilyvjima",
  "uri": "ipfs://bafkreiabepvyxyetkcb3xbjo3ocuyfo6psv3rc3yj34hequwcsilyvjima",
  "metadataURL": "https://cdn.startrail.io/ipfs/bafkreiabepvyxyetkcb3xbjo3ocuyfo6psv3rc3yj34hequwcsilyvjima"
}
```

| Field         | Description                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `cid`         | IPFS CIDv1 of the canonical document                                                                     |
| `uri`         | `ipfs://<cid>` — the value to put in a field that references this document                               |
| `metadataURL` | The document on the [Startrail IPFS CDN gateway](https://docs.startrail.io/subgraph/ipfs-cdn-gateway.md) |
| {% endtab %}  |                                                                                                          |
| {% endtabs %} |                                                                                                          |

## Errors

| Status | Message                                                                                                                  | When                                                                                      | What to do                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | `Missing header` / `API Key is not valid for <issuer-address>`                                                           | Headers missing or key does not belong to the issuer                                      | Fix the headers                                                                                                                               |
| `400`  | `metadata should not be null or undefined` / `metadata must be an object`                                                | No `metadata`, or not a JSON object (an array, a string)                                  | Send `{ "metadata": { … } }`                                                                                                                  |
| `400`  | `metadata exceeds the maximum size of 204800 bytes (serialized size: <n> bytes)`                                         | Document too large                                                                        | Split it; move history into an archive document and reference its CID                                                                         |
| `400`  | `metadata is invalid. $schema path is invalid, cid is not found (no published registry schema for ipfs://<cid>)`         | Registered `$schema` by CID, not published                                                | Use a published CID from the [registry](https://docs.startrail.io/flexible-metadata-registered-schemas/registered-schemas/schema-registry.md) |
| `400`  | `metadata is invalid. $schema path is invalid, file is not found (no published registry schema named <name> v<version>)` | Registered `$schema` by name, no published version matches (`v<version>` only when given) | Check the name and version                                                                                                                    |
| `400`  | `metadata failed validation against JSON schema. Details: <path> <message> (<params>). …`                                | The document breaks its registered schema (latest version, pinned form)                   | Fix the fields named in `Details`                                                                                                             |
| `400`  | `… Details: refers to a file that is not in storage ({"url":"<url>"}).`                                                  | A storage URL whose file was never uploaded                                               | Upload via `/commerce/signedUrls`                                                                                                             |
| `400`  | `… Details: refers to a file whose CID is not calculated yet, retry shortly ({"url":"<url>"}).`                          | File uploaded, CID pending                                                                | Poll `/commerce/fileMetadata`, retry                                                                                                          |
| `500`  | `schema registry resolution failed`                                                                                      | Registry unreachable                                                                      | Retry                                                                                                                                         |
| `500`  | `<message>`                                                                                                              | Pinning failed                                                                            | Retry; if it persists [contact us](https://startbahn.io/contact)                                                                              |
| `503`  | `<message>`                                                                                                              | IPFS pinning is not configured on this environment                                        | [Contact us](https://startbahn.io/contact)                                                                                                    |

The closed-release check does not apply here: nothing is issued or put on chain.


---

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