Introduction

Miura Nexus API - High-level Python client for the Nexus platform

Miura Nexus API

The Miura Nexus API is a high-level Python client library for the Nexus platform. It provides a clean, intuitive API for managing projects, collections, and data workflows.

Overview

The Nexus API provides a Pythonic interface to the Nexus platform, hiding the complexity of the underlying API calls behind simple Python classes and methods. It enables users to manage projects, collections, and data through a familiar Python interface.

Advanced Features

  • Retry Policies: Configure automatic retries for network operations
  • Hooks: Add observability hooks for request/response/retry events
  • Error Handling: Comprehensive error management with structured exceptions

From PyPI

bash
pip install miura-nexus

Quick Start

Authentication

The Nexus API uses token-based authentication. Set your API key using one of these methods:

Option 1: Environment Variable (Recommended for Services)

bash
export MIURA_NEXUS_API_KEY="your-api-key-here"

Option 2: CLI Storage (Recommended for Interactive Use)

bash
# Set your authentication token
miura-auth token set --token "your-api-key-here"

# Verify token is stored
miura-auth token status

Basic Usage

python
import asyncio
from miura.api import AsyncNexus
from miura.logging import get_logger

logger = get_logger(__name__)

async def main():
    async with AsyncNexus() as nexus:
        # List projects
        projects = await nexus.list_projects()
        logger.info(f"Found {len(projects)} project(s)")
        

        # Create a project
        project = await nexus.create_project("my-project")
        logger.info(f"Created project: {project.name}")
        

        # Create a collection with schema
        collection = await project.create_collection(
            collection_name="my-collection",
            schema=[{"pattern": ".*\\.vtk$", "min_occurrence": 1}]
        )
        logger.info(f"Created collection: {collection.name}")

asyncio.run(main())

## Documentation Structure

### Getting Started
- **[Getting Started Guide](/docs/v0.20.1/getting-started)** - Start here! Get up and running quickly with authentication, configuration, and basic usage examples.

### Progressive Tutorials

These tutorials are designed to be followed in order, each building on the previous one:

1. **[Projects and Collections](/docs/v0.20.1/projects-and-collections)** - Create and manage projects and collections using different navigation styles
2. **[Schemas](/docs/v0.20.1/schemas)** - Understand schemas as quality gates for data ingestion
3. **[Uploading Data](/docs/v0.20.1/uploading-data)** - Upload data to collections with automatic schema validation
4. **[Fetching Data](/docs/v0.20.1/fetching-data)** - List, iterate, retrieve, and download collection items
5. **[End-to-End Workflows](/docs/v0.20.1/end-to-end-workflows)** - Complete, real-world workflows combining all features

## Key Concepts

### Navigation Styles

The API supports two navigation styles, both equally supported:

- **Object-Oriented**: `nexus.get_project()` → `project.get_collection()` → `collection.get_item()`
- **Path-Based**: `nexus.get("project/collection/item")`

### Schemas as Quality Gates

**Schemas are quality gates for data ingestion.** They ensure:
- Only properly structured data enters your collection
- Data consistency across all uploads
- Early detection of problems (during prevalidation)
- Clear documentation of expected data structure

### Async vs Sync

- **Async API** (`miura.api`): Primary interface, use for new code
- **Sync API** (`miura`): Compatibility layer for synchronous code or Jupyter notebooks

:::tip
New to the Nexus platform? Start with our [Getting Started guide](/docs/v0.20.1/getting-started) to learn the fundamentals before diving into advanced features.
:::

Basic Examples

Basic examples for using the Nexus API

Getting Started

Nexus Quick Start - Get up and running with the Miura Nexus API in minutes

© 2026