Skip to navigation
About

Architecture Overview

View as Markdown

The NIM Metadata API exposes metadata populated by the NIM build process at publish time. A client reads profiles and requirements over HTTP before pulling a container. This page describes that documented publication and consumption flow; endpoint details are in Endpoints.

Components

The following components publish and consume NIM metadata:

ComponentRole
NIM build and publishing processPopulates metadata for a NIM microservice and container tag.
Tag-level metadata documentRecords profiles, release details, features, and related URLs when those values are supplied at publish time.
NIM Metadata APIReturns the document through equivalent HTTP GET request forms.
HTTP client or automated consumerInterprets optional fields and compares profiles against hardware and workload requirements.
NIM microservice containerRuns the selected profile after deployment. Access to its metadata does not grant entitlement to pull the container.

Data Flow

Metadata moves from publication to profile selection in the following sequence:

  1. The NIM build process populates metadata at publish time.
  2. The client identifies the NIM microservice by resourceId and container tag.
  3. The client sends an HTTP GET request to api.ngc.nvidia.com.
  4. The API returns JSON metadata or an NGC error envelope.
  5. The client evaluates profiles and records a chosen profile_id for deployment.
GET: resourceId and tag JSON metadata orerror envelope profile_id NIM buildand publication Tag-level metadata NIM Metadata API HTTP client orautomated consumer Hardware fit andprofile selection NIM deployment

The response contains only populated values. Missing hardware requirements remain unknown. A 404 response can indicate missing metadata or an incorrect repository path form. Refer to Troubleshooting for 404 checks and Core Concepts Overview for interpretation rules.

Deployment Topologies

The API is a hosted HTTP service, so there is no metadata server to install as part of this reader workflow. Clients can query it interactively or from automated tooling:

AspectInteractive ClientAutomated Consumer
PurposeInspect a response and compare profiles for known hardware.Select candidates from tooling, schedulers, or agents.
Interfacecurl or a Python HTTP client.An HTTP client with explicit handling of absent fields and status codes.
GuidanceQuickstartNotes for Automated Agents

Service Interactions

All three metadata request forms return the same JSON body for the same NIM microservice and tag. The following sequence shows the read interaction:

alt [Tag and path are correct] [Tag or path needs correction] alt [Metadata available] [404 response] GET metadata for resourceId and tag 200 and JSON metadata Compare profiles and retain profile_id 404 and NGC error envelope Verify container tag and repository path Consult microservice documentation Retry with corrected tag and repository path Client NIM Metadata API

The protocol is HTTPS with JSON responses. For error responses, clients branch on the HTTP status code and requestStatus.statusCode and record requestStatus.requestId for diagnosis.

External Integration Points

The following interfaces provide complementary information:

IntegrationDetails
NGC repository endpointsProvide container-level identity and model information in addition to the metadata API’s tag-level document.
NGC GPU metadata endpointResolves the device portion of a GPU PCI identifier to display names.
Deployment toolingConsumes the selected profile_id according to the deployment instructions for the NIM microservice.

For request forms and examples, refer to Endpoints.