> This page is for version 1.0.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 1.0.0 (Latest) (default): https://docs.nvidia.com/nim/metadata-api/1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nim/metadata-api/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nim/metadata-api/_mcp/server.

# Architecture Overview

> Understand how published NIM profile metadata reaches HTTP clients and supports hardware selection before deployment.

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](/nim/metadata-api/reference/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.

```mermaid
%%{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](/nim/metadata-api/troubleshooting)
for 404 checks and [Core Concepts Overview](/nim/metadata-api/about/core-concepts) 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](/nim/metadata-api/get-started/quickstart)      | [Notes for Automated Agents](/nim/metadata-api/guides/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:

```mermaid
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
[Endpoints](/nim/metadata-api/reference/endpoints).

## Related Topics

* [Overview](/nim/metadata-api/about/overview)
* [Ecosystem Overview](/nim/metadata-api/about/ecosystem)
* [Choose a Profile for Your Hardware](/nim/metadata-api/guides/choose-a-profile)
* [Response Fields](/nim/metadata-api/reference/response-fields)