Is this page helpful?

Endpoints for NIM Metadata API#

Three request forms that use the HTTP GET method are available. All three return the same JSON response body for the same NIM microservice and tag, so choose whichever fits how you hold the identifier. All requests use the following base URL:

https://api.ngc.nvidia.com/v2

The path forms and the query form are equivalent. The path forms construct the resourceId on your behalf.

Query-Parameter Form#

Use this form when you hold the repository path as a single string.

GET /v2/nim/metadata?resourceId={resourceId}&tag={tag}

The following table describes the parameters:

Parameter	In	Required	Description
`resourceId`	query	Yes	Repository path, in the form `{org}/{repo-name}` or `{org}/{team-name}/{repo-name}`. Must not contain a colon.
`tag`	query	Yes	Container tag.

The following example requests metadata for a team-owned NIM microservice:

curl --request GET \
  --url 'https://api.ngc.nvidia.com/v2/nim/metadata?resourceId=nim/meta/llama-3.1-8b-instruct&tag=2.0.12' \
  --header 'accept: application/json'

Omitting either parameter returns a 400 status code.

Note

URL-encode the resourceId if your client does not do so automatically. The slashes are literal and must survive to the server.

Path Form, Team-Qualified#

Use this form for a repository that sits inside a team within the organization.

GET /v2/nim/{team-name}/{repo-name}/{tag-name}/metadata

The following table describes the parameters:

Parameter	In	Required	Description
`team-name`	path	Yes	Team owning the repository.
`repo-name`	path	Yes	NIM microservice container name.
`tag-name`	path	Yes	Container tag.

The following example uses the team-qualified path form:

curl --request GET \
  --url 'https://api.ngc.nvidia.com/v2/nim/meta/llama-3.1-8b-instruct/2.0.12/metadata' \
  --header 'accept: application/json'

Path Form, Organization Root#

Use this form for a repository that sits directly under the organization with no team.

GET /v2/nim/{repo-name}/{tag-name}/metadata

The following example uses the organization-root path form:

curl --request GET \
  --url 'https://api.ngc.nvidia.com/v2/nim/openfold3/1.2.0/metadata' \
  --header 'accept: application/json'

Note

No organization-root NIM microservice container exists in production today. The preceding command illustrates the path form only. Do not use it as a live test target.

Important

Segment count alone distinguishes the two path forms. A team-owned NIM microservice requested through the organization-root form returns a 404 status code rather than resolving silently. If you receive an unexpected 404 status code, confirm that you are using the form that matches the actual layout of the repository. To check the layout, search for the NIM microservice on the NGC Catalog and review the URL path.

The service supplies the organization for both path forms, which is why it does not appear in the path.

Responses#

The following table describes the status codes this endpoint returns:

Status Code	Meaning
200	Metadata returned.
400	Malformed request.
404	No metadata exists for this NIM microservice and tag.
500	Internal error.

Errors use the standard NGC envelope:

{
  "requestStatus": {
    "statusCode": "NOT_FOUND",
    "statusDescription": "NIM metadata does not exist for nim-metadata/openfold3:1.2.0",
    "requestId": "f2ee19e1-48e0-4a34-a148-86f3e78f0bf6"
  }
}

A request that uses the GET method returns one of the following statusCode values:

INVALID_REQUEST for a 400 status code
NOT_FOUND for a 404 status code
INTERNAL_ERROR for a 5xx status code

Note

The namespace in statusDescription refers to the internal metadata storage for the service and does not match the resourceId you sent. This is expected, and it is one more reason to branch on the status code rather than on the description text.

A 400 status code on this endpoint does not always mean your request was malformed. Stored metadata that fails validation on read also surfaces as a 400 status code, and metadata that cannot be parsed at all surfaces as a 500 status code. Consider a 400 status code service-side when your request is well-formed and the description does not name one of your parameters. Report that case rather than retrying with different parameters. For details, refer to Troubleshooting.

Always log requestStatus.requestId, because that is the value support needs to trace a specific request.

Endpoints for NIM Metadata API#

Query-Parameter Form#

Path Form, Team-Qualified#

Path Form, Organization Root#

Responses#

Related Topics#