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

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

```python
from nemo_platform import NeMoPlatform

client = NeMoPlatform()

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

### Constructor

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

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

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

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

```python
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](/documentation/reference/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
* **workspaces.members**: Workspace member and RBAC management

### Response Handling

* **with\_raw\_response**: Access raw HTTP response data
* **with\_streaming\_response**: Handle streaming responses