> For the complete documentation index, see [llms.txt](https://run-ai-docs.nvidia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://run-ai-docs.nvidia.com/api/2.25/api-python-client-reference/api-python-client-runapy.md).

# API Python Client (runapy)

The NVIDIA Run:ai Community Python Client (`runapy`) provides a comprehensive, production-ready interface for interacting with the NVIDIA Run:ai platform's REST API. This client simplifies the process of programmatically managing your AI workloads, resources, and infrastructure without requiring manual API token handling or custom API integrations.

Refer to the [runapy GitHub repository](https://github.com/runai-professional-services/runapy) for more details.

{% hint style="warning" %}
**Important**

This Python client was developed by the NVIDIA Run:ai Professional Services team and is provided as is. It is not an official component of the NVIDIA Run:ai product and is not maintained by the NVIDIA Run:ai engineering team.
{% endhint %}

## Key Features

* **Unified interface** - Access all NVIDIA Run:ai REST API operations through a single client.
* **Automatic authentication** - Automatically handles API token refresh for long-running sessions.
* **Robust networking** - Includes built-in retry mechanism with exponential backoff for transient network errors.
* **Type safety** - Uses Pydantic models for runtime data and validation and serialization
* **Multiple client modes** - Supports synchronous, threaded, and asynchronous operations.
* **Production-ready** - Offers comprehensive error handling and logging for enterprise environments

## Versioning

The NVIDIA Run:ai API is an integral part of the control plane microservices. As the control plane evolves, the API may introduce additions, modifications, or deprecations. This version binding ensures that API changes in the client match the control plane capabilities.

The client follows semantic versioning (X.Y.Z) with a special alignment to NVIDIA Run:ai's control plane versions:

* **X (Major)** - Major changes in the client
* **Y (Minor)** - NVIDIA Run:ai control-plane version (e.g., 219 for control-plane 2.19)
* **Z (Patch)** - Small bug fixes and non-breaking changes

For example:

```
1.218.0  # Initial release for control-plane 2.18
1.218.1  # Patch release for control-plane 2.18
1.219.0  # Initial release for control-plane 2.19
```

This versioning convention ensures that:

* Each control plane version has a corresponding client version
* Client versions clearly indicate their compatible control plane version
* Client breaking changes are managed in major version bumps

## API Structure

The Python client mirrors the structure of the NVIDIA Run:ai REST API documentation using three levels:

1. **API categories** - Top-level groupings (e.g., `organizations`, `authentication_and_authorization`)
2. **API groups** - Resource-specific groups within categories (e.g., `projects`, `departments` under `organizations`)
3. **API methods** - Individual operations on resources (e.g., `get_projects`, `create_project`)

Example of navigating the API structure:

```python
# List available API groups in the organizations category
client.organizations.options()
# ['projects', 'departments', 'clusters', 'nodes', ...]

# List available methods in the projects group
client.organizations.projects.options()
# ['get_projects', 'create_project', 'delete_project', ...]
```

## Deprecated Methods

Deprecated methods are hidden by default. To view both supported and deprecated methods, use the `include_deprecated` flag:

```python
client.organizations.projects.options(include_deprecated=True)
```

## Examples

The repository provides:

* [Hand-crafted examples](https://github.com/runai-professional-services/runapy/tree/main/examples) - Common use cases with clean syntax
* [Auto-generated examples](https://github.com/runai-professional-services/runapy/tree/main/examples/generated) - Located under `/examples/generated` (some may require minor edits)

The client exposes nearly all API functionality available in the NVIDIA Run:ai UI. If a workflow isn’t shown in the examples directory, check the relevant API category directly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://run-ai-docs.nvidia.com/api/2.25/api-python-client-reference/api-python-client-runapy.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
