> This page is for Structured Data Models Client.

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

# NIM REST API

> Call Kumo Relational through the Universal Structured Data Foundation Models REST contract

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](https://docs.api.nvidia.com/nim/reference/nvidia-kumo-relational).

## 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](https://github.com/NVIDIA/structured-data-models-client/blob/v1.0.0/tests/golden/wire_payloads.json) include a complete relational count-regression request. Save that request as `request.json`:

```python
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.

```bash
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.