Skip to navigation
Kumo RelationalReference

NIM REST API

View as Markdown

Kumo Relational is served through the Universal Structured Data Foundation Models (TFM) API — the same contract sdm-client’s generated bindings (structured-data-models-api) speak. Use the Python SDK for standard workflows; use REST directly for service integration or OpenAPI client generation.

Choose an endpoint

  • Self-hosted NIM: Use the base URL of your deployment. The NIM does not require authentication as part of its API contract, but a gateway in front of it might require an API key or another credential.
  • NVIDIA API Catalog: Use the server URL and bearer-token authentication shown in the Kumo Relational API reference.

Run a one-shot prediction

The POST /v1/predictions endpoint accepts a complete Universal TFM request that contains the model, task, relational schema, labeled context, rows to predict, requested outputs, and optional inference settings and metadata. It returns the prediction synchronously and does not create a durable prediction resource.

The client’s versioned wire-request examples include a complete relational count-regression request. Save that request as request.json:

import json
from urllib.request import urlopen
url = (
    "https://raw.githubusercontent.com/NVIDIA/structured-data-models-client/"
    "v1.0.0/tests/golden/wire_payloads.json"
)
with urlopen(url) as response:
    examples = json.load(response)
request = examples["relational/pql-count-aggregation"][0]
with open("request.json", "w") as output:
    json.dump(request, output)

This small fixture demonstrates the request format; it does not measure prediction quality. Replace its sample data and task with your own after verifying that your deployment accepts it.

curl --fail-with-body \
  --request POST \
  --url "${SDM_RELATIONAL_URL}/v1/predictions" \
  --header "Content-Type: application/json" \
  --data @request.json

Before running the command, set SDM_RELATIONAL_URL to the base URL of your deployment, such as http://localhost:8000. If applicable, add the authentication header required by your gateway. For the NVIDIA API Catalog endpoint, use the Authorization: Bearer $NVIDIA_API_KEY header, as shown in the generated API examples.

Sessions

POST /v1/sessions pins a context without running inference; POST /v1/sessions/{session_id}/predictions scores against it; DELETE /v1/sessions/{session_id} releases it. This is what SDMClient.fit() and FittedModel.predict()/close() call under the hood.

Response and errors

A successful response contains a response-level correlation ID, the model name, prediction items, and metadata. Each prediction item includes a zero-based row_index. It can include the input id and requested fields such as prediction and probabilities.

Errors use application/problem+json with fields such as type, status, title, detail, and code. A request refused for exceeding a size limit, or an output a deployment does not serve, uses 422 with a code such as UNSUPPORTED_SHAPE or UNSUPPORTED_OUTPUT. See the generated API reference for the complete request schema, response schema, error model, and runnable examples.