Skip to main content

Add metadata to entities

Once you've defined a metadata specification, the next step is to attach metadata entries to specific entities like builds, applications, or namespaces. This step adds actual values to the attributes defined in your specification — such as coverage numbers, aliases, deployment regions, or tags.

What is a metadata entry?​

A metadata entry is a JSON object that:

  • Fills out the fields defined in a catalog specification
  • Is scoped to a specific entity (e.g., a build or namespace)
  • Is validated against the corresponding JSON Schema

Two ways to attach metadata​

You can choose between:

MethodDescriptionUse case
Batch entrySend multiple metadata keys at once for one entity specWhen updating several fields together
Per-key entrySend a single metadata key and value per requestWhen dealing with dynamic forms or integrations

Example: multiple entries on a build​

Imagine you want to attach test coverage and vulnerability reports to a build. You’d send both catalog keys in one payload like this:

{
  "coverage": {
    "percent": 95,
    "report": "https://reports.example.com/build/coverage.html"
  },
  "vulnerabilities": {
    "high": 0,
    "low": 2,
    "report": "https://reports.example.com/build/vuln.html"
  }
}

Create metadata entries via API​

Create multiple entries in one request​

Here's an example request for multiple entries for a build. For this you'll need to make a POST request to create metadata entries for multiple specification.

np metadata create
--id :id
--entity build
--body '{
 "coverage": {
     "percent": "95",
     "report": "https://reports.my-organization.com/coverage/build-a82c3d45-19e6-4f2b-b7d0-63f9a1842c1e.html"
 },
 "vulnerabilities": {
     "high": 0,
     "medium": 0,
     "low": 2,
     "report": "https://reports.my-organization.com/vulnerabilities/build-d4e5f678-2a31-4c89-9b01-ef45d32a7b90.html"
 }
}'

Create a single metadata key for an entity​

To update only one catalog field (e.g., just coverage), send a POST request to create a metadata entry for a particular specification.

curl -L -X POST 'https://api.nullplatform.com/metadata/build/:id/coverage' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
  "percent": 95,
  "report": "https://reports.my-org.com/coverage/build-123.html"
}'

Read all metadata for an entity​

To retrieve everything attached to an entity, make a GET request:

np metadata read
--id :id 
--entity build

This returns a complete view of the entity's catalog data, enriched with schema and tag information.

Next steps​