Getting Started

Get started with the Miura Nexus API in minutes. This guide covers installation, authentication, and your first API call.

Install the Package

pip install miura-epico

Or with Poetry:

poetry add miura-epico

Configure Authentication

Get Your API Key:

1. Sign in to the Nexus Portal
2. Navigate to your profile settings
3. Generate or copy your API key

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

Option 1: Environment Variable (Recommended for Services)

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

Or add it to your .env file:

MIURA_NEXUS_API_KEY=your-api-key-here

Option 2: CLI Storage (Recommended for Interactive Use)

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

# Verify token is stored
miura-auth token status

# Test authentication
miura-auth test

Storage Backends:

• --storage=file (default): Stores token in a secure file
• --storage=keyring: Stores token in system keyring

Your First API Call

Here's a simple example to get you started. The sync API is perfect for quick scripts and interactive use:

from miura import Nexus
from miura.logging import get_logger

logger = get_logger(__name__)

with Nexus() as nexus:
    # List existing projects
    projects = nexus.list_projects()
    logger.info(f"Found {len(projects)} project(s)")
    for project in projects:
        logger.info(f"  - {project.name} ({project.uuid})")
    # Nexus automatically closes when exiting the with block

That's it! The with statement ensures proper resource cleanup. You can now explore your projects, create collections, and manage your data.

For async code, use the async API:

import asyncio
from miura.aio import AsyncNexus
from miura.logging import get_logger

logger = get_logger(__name__)

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

asyncio.run(main())

Core Concepts

• Projects - Top-level containers for organizing your work
• Collections - Data containers within projects, defined by schemas
• Items - Files and folders within collections
• Schemas - Quality gates that validate data structure during ingestion

See the Projects and Collections guide for detailed information.

Navigation Styles

The API supports two navigation styles, both equally supported:

• Object-Oriented Navigation - Navigate through objects (async API)
• Path-Based Navigation - Navigate using hierarchical paths (sync API)

See the Projects and Collections tutorial for a detailed comparison and when to use each style.

Async vs Sync

Sync API (miura) - Simple and straightforward, perfect for scripts and interactive use:

from miura import Nexus

with Nexus() as nexus:
    projects = nexus.list_projects()

Async API (miura.aio) - Primary interface for production code, use for async applications:

from miura.aio import AsyncNexus

async with AsyncNexus() as nexus:
    projects = await nexus.list_projects()

Both APIs are fully featured and equally supported. Choose based on your use case.

Next Steps

Now that you're set up, explore these guides:

• Projects and Collections - Create and manage projects and collections
• Schemas - Learn about schemas and schema generation
• Uploading Data - Upload files and folders to collections
• Fetching Data - List, retrieve, and download items
• End-to-End Workflows - Complete examples
• Code Examples - Full Python code examples
• API Reference - Complete API documentation

Troubleshooting

Authentication Errors:

1. Verify your token: miura-auth token status
2. Check environment variable: echo $MIURA_NEXUS_API_KEY
3. Test authentication: miura-auth test

Not Found Errors:

• Use list_projects() or list_collections() to see available resources
• Check resource names (case-sensitive)
• Create resources if they don't exist

Connection Errors:

• Configure retry policy with more retries
• Increase timeout values
• Check network connectivity

For more detailed troubleshooting and advanced usage, see the API Reference.