---
title: "Enrich packages with custom metadata"
description: "Custom key-value metadata can now be attached to any package in Cloudsmith, making it possible to store structured contextual data - CI build info, Git provenance, compliance evidence, cost attribution - directly alongside the artifact it describes. "
canonical_url: "https://cloudsmith.com/changelog/enrich-packages-with-custom-metadata"
last_updated: "2026-06-16T13:25:03.330Z"
---
# Enrich packages with custom metadata

Custom key-value metadata can now be attached to any package in Cloudsmith, giving structured contextual data - CI build info, Git provenance, commit SHAs, internal attribution - a proper home alongside the artifact it describes. Stored as arbitrary JSON key-value pairs, it's purpose-built for the kind of contextual data that doesn't belong in tags.

```json
{
  "_key": "4d9404608327",
  "_type": "image",
  "alt": "Custom metadata displayed on a package in the Cloudsmith web app.",
  "asset": {
    "_createdAt": "2026-06-17T13:00:47Z",
    "_id": "image-2b480cf41ddab7bc1dfd9b2c2774ef238d42cb90-1728x1816-png",
    "_rev": "v47e9Exdh3U7ZUs8SyUUqF",
    "_type": "sanity.imageAsset",
    "_updatedAt": "2026-06-17T13:00:47Z",
    "assetId": "2b480cf41ddab7bc1dfd9b2c2774ef238d42cb90",
    "extension": "png",
    "metadata": {
      "_type": "sanity.imageMetadata",
      "blurHash": "e5SsBHS*R:_3-;~qt6E0RjWBD*ogWBayofS%t7ayofayxut6Rjj?j?",
      "dimensions": {
        "_type": "sanity.imageDimensions",
        "aspectRatio": 0.9515418502202643,
        "height": 1816,
        "width": 1728
      },
      "hasAlpha": true,
      "isOpaque": false,
      "lqip": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAYAAABG1c6oAAAACXBIWXMAAAsTAAALEwEAmpwYAAACC0lEQVR4nKVUy5LTQBDL//8YXOEEHwBU7VJJ7Hn2a0R1jycJHFjYHFT2uGxZmpbmlCqPvRIcl9zxc2tITUAy3sTLOeHj56/48OkLvr1eRqpsp8aC0gg5wNiLoJFCDW/Cv/vxesb3lzP20lFJcGJVlE7ItaN2QuuuTjHGwBj4K8wGRHRCDSyKk9pAJUVy27kgl4pODDM7SP8dqrYIDVshXPccpMRPEjY2pOIKG3JtzxGaDbAYSpMYSmeGqMb+vItw+E2o1JgSsUDNYOMJQhsDnQ2lc0ShEYNlEr9bYWdDDcKO2ghEbt3ejM54gOo4FJonX4PQyfozCs0slHRWNFfoAW89FPoL/0MoERvVUOQN6SRo0RZXSWCWhybo/MGh+hYru6+PplhMN1dBqYRcGlKpN+y5IuUaDVrKPQmeVRdCvODPdObQm5LqvX7emIXzlnDedlz3dKvm+qmvk69rC1dBuKq3V8VeGFsquGz7jeTixCnFh66w9omZhh73c4jzgJiEXbEVwZYpCM7XHZfNFbltr2M9FNztPlpmlkl4P20Oy4Ww5YItZaRcQsVSMoe1jrj5zBNRWkN1+CBZ/rRMuKaC60Ho++WEK5f3AXAM57ehiKt8PG2aE/Ygc7s+kFBapl239Ui4YrV67xC1cRKFEdtwld5j3zPfu7l/aw9b2POrI1V/p4TtdTKp2WBR+wXh4m++WA0tsQAAAABJRU5ErkJggg==",
      "palette": {
        "_type": "sanity.imagePalette",
        "darkMuted": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#324d5c",
          "foreground": "#fff",
          "population": 0.02,
          "title": "#fff"
        },
        "darkVibrant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#091b2d",
          "foreground": "#fff",
          "population": 0.04,
          "title": "#fff"
        },
        "dominant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#a1adc8",
          "foreground": "#000",
          "population": 0.1,
          "title": "#fff"
        },
        "lightMuted": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#a1adc8",
          "foreground": "#000",
          "population": 0.1,
          "title": "#fff"
        },
        "lightVibrant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#a4b4dc",
          "foreground": "#000",
          "population": 0,
          "title": "#fff"
        },
        "muted": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#668494",
          "foreground": "#fff",
          "population": 0.01,
          "title": "#fff"
        },
        "vibrant": {
          "_type": "sanity.imagePaletteSwatch",
          "background": "#2a7fd4",
          "foreground": "#fff",
          "population": 0,
          "title": "#fff"
        }
      },
      "thumbHash": "/veBBQAPcuyeYpEGmjCYApQJBwd4eICABw=="
    },
    "mimeType": "image/png",
    "originalFilename": "image (20).png",
    "path": "images/rafvlnhi/production/2b480cf41ddab7bc1dfd9b2c2774ef238d42cb90-1728x1816.png",
    "sha1hash": "2b480cf41ddab7bc1dfd9b2c2774ef238d42cb90",
    "size": 215768,
    "uploadId": "76b96217ef6769d40b744039613a589ed27002b7",
    "url": "https://cdn.sanity.io/images/rafvlnhi/production/2b480cf41ddab7bc1dfd9b2c2774ef238d42cb90-1728x1816.png"
  },
  "caption": "Custom metadata displayed on a package in the Cloudsmith web app.",
  "link": {
    "_type": "link",
    "href": null,
    "openInNewTab": false
  },
  "markDefs": null
}
```

## How it works

Custom metadata can be added, updated, deleted, viewed, and searched via the Cloudsmith API and CLI. Once attached, metadata can be used in policy-as-code matching logic and the Cloudsmith package search filter, making it possible to enforce governance and find packages based on the contextual data you've stored.

```json
{
  "_key": "8c6cfd569f1a",
  "_type": "tableBlock",
  "caption": "Currently supported custom metadata functionality for the Cloudsmith API, CLI, and web app. Metadata can only be created, updated, and deleted via the API or CLI - the web app supports viewing and searching existing metadata only.",
  "firstRowIsHeader": true,
  "markDefs": null,
  "table": {
    "rows": [
      {
        "_key": "71692915-87ee-41f3-aeba-08b27050701b",
        "_type": "tableRow",
        "cells": [
          "",
          "Add",
          "Update",
          "Delete",
          "View",
          "Package search filter"
        ]
      },
      {
        "_key": "c1c9211d-8852-4c7d-bf90-595f035ee442",
        "_type": "tableRow",
        "cells": [
          "API",
          "✓",
          "✓",
          "✓",
          "✓",
          "✓"
        ]
      },
      {
        "_key": "64c615d5-6a75-4a5c-a8cf-f77621a8783b",
        "_type": "tableRow",
        "cells": [
          "CLI",
          "✓",
          "✓",
          "✓",
          "✓",
          "✓"
        ]
      },
      {
        "_key": "d1671594-80e2-41d7-9286-eaf16cfe1492",
        "_type": "tableRow",
        "cells": [
          "Web app",
          "",
          "",
          "",
          "✓",
          "✓"
        ]
      }
    ]
  }
}
```

### Package search

The Cloudsmith package search now supports a `metadata` filter.

For more information about using the package search, see [Package search syntax](https://docs.cloudsmith.com/artifact-management/search-filter-sort-packages).



## Getting started

Custom metadata is currently available in early access for Ultra and Enterprise customers. If you have any questions or feedback on this feature, please [contact us](/company/contact-us).

Learn more about custom metadata in our [documentation](https://docs.cloudsmith.com/artifact-management/custom-metadata).