Documentation
Book a demo

Arbitrary metadata

Managing arbitrary metadata via the Cloudsmith API

Early Access

Arbitrary metadata is currently available in early access for Ultra and Enterprise customers. To request early access, contact us.

You can manage package metadata via the Cloudsmith API by using the following endpoints:

Attaching key-value metadata to a package

Validate a metadata payload

Before attaching metadata to a package, you can validate the metadata payload against the JSON schema for its content_type without persisting it. Returns 200 on success and 422 on validation failure, with the same field-level error shape as the create endpoint.

Example:

bash
curl -X POST https://api.cloudsmith.io/api/v2/metadata/validate

Attach metadata to a package

You can POST arbitrary JSON key-value pairs to a package by using the v2 metadata API. This accepts any JSON object.

Example:

bash
curl -X POST 'https://api.cloudsmith.io/api/v2/metadata/packages/{package_slug_perm}/' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": {
        "team": "platform-engineering",
        "environment": "staging",
        "build_commit": "a1b2c3d4e5f6",
        "approved_by": "jane.doe@cloudsmith.com",
        "deploy_target": "us-east-1",
        "custom_tags": ["release-candidate", "needs-qa"]
    },
    "content_type": "application/json",
    "source_identity": "demo:artifact-metadata"
}'

Response:

bash
Metadata created (HTTP 201)
{
  "slug_perm": "uJSv0s1NSkGi",
  "content": {
    "team": "platform-engineering",
    "environment": "staging",
	  "build_commit": "a1b2c3d4e5f6",
    "approved_by": "jane.doe@cloudsmith.com",
    "deploy_target": "us-east-1",
    "custom_tags": [
	    "release-candidate",
	    "needs-qa"
    ]
  },
  "content_type": "application/json",
  "source_identity": "demo:artifact-metadata"
}

Viewing metadata for a package

You can list all of the metadata entries for a package, or retrieve a single entry by its slug_perm.

Examples:

List all metadata entries for a package:

bash
curl https://api.cloudsmith.io/api/v2/metadata/packages/{package_slug_perm}/

Retrieve a single metadata entry by its slug_perm:

bash
curl https://api.cloudsmith.io/api/v2/metadata/packages/{package_slug_perm}/{metadata_slug_perm}

Filtering metadata for a package

The metadata API supports query-parameter filtering by classification and source kind.

Note

Customer-provided key-value metadata has the GENERIC classification and the CUSTOM source kind.

Examples:

Filter metadata entries with the GENERIC classification for a package:

bash
curl 'https://api.cloudsmith.io/api/v2/metadata/packages/{package_slug_perm}?classification=GENERIC'

Filter metadata entries with the CUSTOM source kind for a package:

bash
curl 'https://api.cloudsmith.io/api/v2/metadata/packages/{package_slug_perm}?source_kind=CUSTOM'

Removing metadata from a package

You can remove a specific metadata entry from a package by using the slug_perm for the entry:

bash
curl -X DELETE https://api.cloudsmith.io/api/v2/metadata/packages/{package_slug_perm}/{metadata_slug_perm}/

Response:

bash
The metadata entry was removed successfully. (HTTP 204)

Updating metadata for a package

You can update a specific metadata entry for a package by using the slug_perm for the entry.

You can update the values for the content_type, source_identity, and content fields of the metadata entry.

Warning

Updating the metadata will replace the current content for the specified fields.

If you want to update the content field, you must also resubmit the key-value pairs that you want to retain unchanged.

Example: Updating the value of the deploy_target key from us-east-1 to us-east-2

Existing metadata entry:

bash
{
  "slug_perm": "uJSv0s1NSkGi",
  "content": {
    "team": "platform-engineering",
    "environment": "staging",
	  "build_commit": "a1b2c3d4e5f6",
    "approved_by": "jane.doe@cloudsmith.com",
    "deploy_target": "us-east-1",
    "custom_tags": [
	    "release-candidate",
	    "needs-qa"
    ]
  },
  "content_type": "application/json",
  "source_identity": "demo:artifact-metadata"
}

Update request:

bash
curl -X PATCH 'https://api.cloudsmith.io/api/v2/metadata/packages/{package_slug_perm}/{metadata_slug_perm}/' \
   -H 'Content-Type: application/json' \
   -d '{
    "content": {
        "team": "platform-engineering",
        "environment": "staging",
        "build_commit": "a1b2c3d4e5f6",
        "approved_by": "jane.doe@cloudsmith.com",
        "deploy_target": "us-east-2",
        "custom_tags": ["release-candidate", "needs-qa"]
     },
   }'

Response:

bash
The metadata entry was updated successfully. (HTTP 200)

{
  "slug_perm": "uJSv0s1NSkGi",
  "content": {
    "team": "platform-engineering",
    "environment": "staging",
	  "build_commit": "a1b2c3d4e5f6",
    "approved_by": "jane.doe@cloudsmith.com",
    "deploy_target": "us-east-2",
    "custom_tags": [
	    "release-candidate",
	    "needs-qa"
    ]
  },
  "content_type": "application/json",
  "source_identity": "demo:artifact-metadata"
}

Searching for packages with metadata filters

The packages API supports a metadata: search prefix with:

  • Basic key-value matching
  • Nested keys using a _ separator
  • Relational operators on numeric values
  • Negation

Examples

To search for packages with an environment=staging key-value metadata pair, your search query would be:

bash
query=metadata:environment:staging

Response:

bash
✓ Found 1 package(s) matching metadata:environment:staging (HTTP 200)
  {
    "name": "cloudsmith-python-cli",
    "version": "1.0.12345",
    "slug_perm": "{package_slug_perm}"
  }

To search for packages by using a nested metadata key path like deploy_target, your search query would be:

bash
query=metadata:deploy_target:us-east-1

Response:

bash
✓ Found 1 package(s) matching metadata:deploy_target:us-east-1 (HTTP 200)
  {
    "name": "cloudsmith-python-cli",
    "version": "1.0.12345",
    "slug_perm": "{package_slug_perm}"
  }

To search for packages with a key-value metadata pair matching build_number ≥ 40, your search query would be:

bash
query=metadata:build_number: ≥ 40

Response:

bash
✓ Found 1 package(s) with build_number ≥ 40 (HTTP 200)
  {
    "name": "cloudsmith-python-cli",
    "version": "1.0.12345",
    "slug_perm": "{package_slug_perm}"
  }

To exclude packages with an environment=production key-value metadata pair, your search query would be:

bash
query=~metadata:environment:production

Response:

bash
✓ Found 2 package(s) NOT matching environment:production (HTTP 200)

For more information on searching packages via the API, see Searching packages via the Cloudsmith API.