Skip to navigation
Reference

Endpoints for NIM Metadata API

View as Markdown

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:

ParameterInRequiredDescription
resourceIdqueryYesRepository path, in the form {org}/{repo-name} or {org}/{team-name}/{repo-name}. Must not contain a colon.
tagqueryYesContainer 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.

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:

ParameterInRequiredDescription
team-namepathYesTeam owning the repository.
repo-namepathYesNIM microservice container name.
tag-namepathYesContainer 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'

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.

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 CodeMeaning
200Metadata returned.
400Malformed request.
404No metadata exists for this NIM microservice and tag.
500Internal 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

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.