Is this page helpful?

Architecture Overview for NIM Metadata API#

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:

Component

Role

NIM build and publishing process

Populates metadata for a NIM microservice and container tag.

Tag-level metadata document

Records profiles, release details, features, and related URLs when those values are supplied at publish time.

NIM Metadata API

Returns the document through equivalent HTTP GET request forms.

HTTP client or automated consumer

Interprets optional fields and compares profiles against hardware and workload requirements.

NIM microservice container

Runs 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.

%%{init: {'themeVariables': {'fontSize': '22px'}, 'flowchart': {'rankSpacing': 15, 'nodeSpacing': 30, 'padding': 10}}}%% flowchart TD Build["NIM build<br/>and publication"] --> Metadata["Tag-level metadata"] Metadata --> API["NIM Metadata API"] Client["HTTP client or<br/>automated consumer"] -->|"GET: resourceId and tag"| API API -->|"JSON metadata or<br/>error envelope"| Client Client --> Selection["Hardware fit and<br/>profile selection"] Selection -->|"profile_id"| Deployment["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:

Aspect

Interactive Client

Automated Consumer

Purpose

Inspect a response and compare profiles for known hardware.

Select candidates from tooling, schedulers, or agents.

Interface

curl or a Python HTTP client.

An HTTP client with explicit handling of absent fields and status codes.

Guidance

Quickstart

Notes 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:

sequenceDiagram participant Client participant API as NIM Metadata API Client->>API: GET metadata for resourceId and tag alt Metadata available API-->>Client: 200 and JSON metadata Client->>Client: Compare profiles and retain profile_id else 404 response API-->>Client: 404 and NGC error envelope Client->>Client: Verify container tag and repository path alt Tag and path are correct Client->>Client: Consult microservice documentation else Tag or path needs correction Client->>API: Retry with corrected tag and repository path end end

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:

Integration

Details

NGC repository endpoints

Provide container-level identity and model information in addition to the metadata API’s tag-level document.

NGC GPU metadata endpoint

Resolves the device portion of a GPU PCI identifier to display names.

Deployment tooling

Consumes the selected profile_id according to the deployment instructions for the NIM microservice.

For request forms and examples, refer to For request forms and examples, refer to Endpoints.