Client APIs¶

The following reference provides detailed documentation for the synchronous and asynchronous clients of the NeMo Platform Python SDK.

Synchronous Client¶

Use nemo_platform.NeMoPlatform from regular Python code when you want blocking API calls. The client reads the active CLI context by default, including the base URL, workspace, and authentication settings configured by nemo auth login.

from nemo_platform import NeMoPlatform

client = NeMoPlatform()

for workspace in client.workspaces.list().data:
    print(workspace.name)

Constructor¶

NeMoPlatform(
    *,
    workspace: str | None = None,
    base_url: str | httpx.URL | None = None,
    inference_base_url: str | httpx.URL | None = None,
    config_path: pathlib.Path | None = None,
    context_name: str | None = None,
    access_token: str | None = None,
    timeout: float | httpx.Timeout | None = not_given,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: httpx.Client | None = None,
)

Parameter	Description
`workspace`	Workspace name used by workspace-scoped routes. You can set it on the client or pass it to individual methods that accept a workspace argument.
`base_url`	Base URL for the NeMo Platform API. If omitted, the client reads it from the active CLI context.
`inference_base_url`	Optional override for inference gateway requests. Defaults to `base_url`.
`config_path`	Path to the CLI config file. Defaults to `~/.config/nmp/config.yaml`.
`context_name`	Named CLI context to read from the config file.
`access_token`	Explicit bearer token for automation. Token refresh is not performed for explicit tokens.
`timeout`	Request timeout for API calls. Pass a float in seconds, an `httpx.Timeout`, or `None`.
`max_retries`	Number of automatic retries for transient failures.
`default_headers`	Headers sent with every request.
`default_query`	Query parameters appended to every request.
`http_client`	Custom `httpx.Client`. When provided, config and auth bootstrap are skipped.

Connection Modes¶

Mode	Example	Behavior
CLI context	`NeMoPlatform()`	Reads the active CLI context and uses configured authentication with token refresh.
Named context	`NeMoPlatform(context_name="dev")`	Reads a specific CLI context instead of the active one.
Direct API	`NeMoPlatform(base_url="http://localhost:8080")`	Uses the given URL without reading config or injecting auth headers.
Explicit token	`NeMoPlatform(base_url=url, access_token=token)`	Uses the provided bearer token for API calls.

Use with_options(...) to clone a client with request defaults changed:

short_timeout_client = client.with_options(timeout=10.0)

Asynchronous Client¶

Use nemo_platform.AsyncNeMoPlatform from asyncio applications. It exposes the same resource tree as NeMoPlatform, but API methods are awaited.

import asyncio

from nemo_platform import AsyncNeMoPlatform


async def main() -> None:
    client = AsyncNeMoPlatform()
    page = await client.workspaces.list()
    for workspace in page.data:
        print(workspace.name)


asyncio.run(main())

Async client constructor¶

AsyncNeMoPlatform(
    *,
    workspace: str | None = None,
    base_url: str | httpx.URL | None = None,
    inference_base_url: str | httpx.URL | None = None,
    config_path: pathlib.Path | None = None,
    context_name: str | None = None,
    access_token: str | None = None,
    timeout: float | httpx.Timeout | None = not_given,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: httpx.AsyncClient | None = None,
)

AsyncNeMoPlatform accepts the same connection and authentication parameters as NeMoPlatform. Pass a custom httpx.AsyncClient through http_client only when you need to control the underlying transport directly.

import os

from nemo_platform import AsyncNeMoPlatform

client = AsyncNeMoPlatform(
    base_url=os.environ["NMP_BASE_URL"],
    access_token=os.environ["NMP_ACCESS_TOKEN"],
    workspace="default",
)

Errors¶

Client construction raises RuntimeError if configuration or authentication bootstrap fails. Workspace-scoped methods raise ValueError when no workspace is provided on the client or method call.

API calls raise typed exceptions from nemo_platform, including:

Exception	Typical HTTP status
`BadRequestError`	`400`
`AuthenticationError`	`401`
`PermissionDeniedError`	`403`
`NotFoundError`	`404`
`ConflictError`	`409`
`UnprocessableEntityError`	`422`
`RateLimitError`	`429`
`InternalServerError`	`5xx`

Catch APIStatusError for all non-success HTTP responses, or NeMoPlatformError for SDK-level errors.

Client Attributes¶

The NeMo Platform clients provide access to API resources through the following attributes. For endpoint details, see the REST API Reference.

Organization¶

workspaces: Manage workspaces
projects: Manage projects within a workspace

Model Management¶

models: Model entity CRUD
evaluation: Benchmarks, benchmark jobs, metrics, and metric jobs
inference: Deployments, deployment configs, providers, and OpenAI-compatible gateway

Data & Synthesis¶

data_designer: Synthetic data generation jobs
safe_synthesizer: PII replacement and safe data synthesis jobs
files: File upload and download

Safety & Compliance¶

guardrail: Guardrail configurations and checks
audit: Model safety audit jobs and configs

Platform¶

jobs: Cross-service job management
entities: Generic entity CRUD
secrets: Secret management
iam: Identity and access management
members: Workspace member and RBAC management

Response Handling¶

with_raw_response: Access raw HTTP response data
with_streaming_response: Handle streaming responses