# LoopX API Documentation: A Complete Guide to the Python Public Interface

> Explore the LoopX API documentation a comprehensive guide to the loopx Python package. Access stable programmatic endpoints for status, runtime, quota, and registry modules.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: api-reference
- Published: 2026-08-15

---

**The LoopX API documentation is the official reference for the `loopx` Python package, exposing stable programmatic endpoints through modules like [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py), [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py), and [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py).**

The LoopX API documentation defines how developers interact with the LoopX agent framework programmatically. Rather than a traditional REST API, LoopX provides a **Python-native API surface** through carefully curated modules that enforce a strict public-private boundary. This design ensures that all state mutations flow through validated control-plane logic, making the API both predictable and version-stable.

## What the LoopX API Documentation Covers

The LoopX API documentation encompasses three interconnected sources: the auto-generated MkDocs site (built from [`mkdocs.yaml`](https://github.com/huangruiteng/loopx/blob/main/mkdocs.yaml)), the Markdown book under `docs/book/en/chapters/`, and inline docstrings in the source modules. Together, these document the **four core API areas** that external code should use.

### Status and Observation ([`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py))

Read-only access to LoopX state lives in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py). The primary entry points are:

- **`get_status()`** – Returns a dictionary containing the current goal, active todos, quota consumption, and system health.
- **`observe()`** – Provides streaming or polling views of state changes.
- **`Status` class** – Typed container for structured access to system state.

These functions wrap the internal [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) and [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) modules, ensuring callers cannot accidentally mutate state.

```python
import loopx

# Query current LoopX state through the public API

status = loopx.status.get_status()
print("Current goal:", status["goal"])
print("Active todos:", len(status["todos"]))

```

### Runtime and Goal Execution ([`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py))

Goal lifecycle management resides in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py). Key functions include:

- **`start_goal(name, config)`** – Creates and launches a new goal with validated configuration.
- **`run(task, args)`** – Executes a task within the current goal context.
- **`Runtime` class** – Lower-level interface for turn-by-turn agent loop processing.

This module is the primary entry point for driving LoopX programmatically. The same calls power the CLI commands `loopx start-goal` and `loopx run`.

```python
import loopx

# Launch a new goal through the API

goal_cfg = {"description": "Run a data-clean-up pipeline", "priority": 5}
result = loopx.runtime.start_goal(
    name="optimize-data-pipeline",
    config=goal_cfg
)
print("Goal launched:", result["goal_id"])

```

### Quota and Resource Gating ([`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py))

Capacity enforcement is handled by [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py):

- **`check_quota(resource, amount)`** – Validates whether an operation can proceed without exceeding limits.
- **`Quota` class** – Structured access to quota policies and current consumption.

All resource-intensive operations should pre-check quota through this API.

```python
import loopx

# Verify quota before expensive operations

if loopx.quota.check_quota(resource="cpu", amount=2):
    loopx.runtime.run(task="docker-build", args=["."])
else:
    print("Insufficient quota – defer the operation")

```

### Extension Registry ([`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py))

Plugin discovery and installation are managed through [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py):

- **`install_extension(spec)`** – Adds a new capability, provider, or host extension.
- **`list_extensions()`** – Enumerates registered extensions with version metadata.
- **`Registry` class** – Direct access to the extension loading system.

This API ensures extensions are properly validated and version-compatible before activation.

## API Stability and Version Compatibility

The LoopX API documentation explicitly defines a **stable compatibility range**. As declared in [`docs/book/en/chapters/11-engineering-boundaries.md`](https://github.com/huangruiteng/loopx/blob/main/docs/book/en/chapters/11-engineering-boundaries.md) (line 27-30), extensions and user code must specify their required API version:

```python
requires_loopx_api = ">=1,<2"

```

This semantic versioning guarantee means that code written against LoopX API 1.x will continue functioning across all 1.x releases. Breaking changes only occur at major version boundaries, with migration paths documented in the Markdown book chapters.

## Where to Find LoopX API Documentation

| Documentation Type | Location | Purpose |
|-------------------|----------|---------|
| **Auto-generated reference** | Built from [`mkdocs.yaml`](https://github.com/huangruiteng/loopx/blob/main/mkdocs.yaml) | Searchable HTML docs with request/response schemas |
| **Engineering design docs** | [`docs/book/en/chapters/11-engineering-boundaries.md`](https://github.com/huangruiteng/loopx/blob/main/docs/book/en/chapters/11-engineering-boundaries.md) | API boundaries, compatibility rules, architectural rationale |
| **Source docstrings** | [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py), [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py), [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) | Exact function signatures, type hints, parameter descriptions |
| **Quick-start examples** | [`README.md`](https://github.com/huangruiteng/loopx/blob/main/README.md) | CLI-to-API mapping, common usage patterns |

The MkDocs configuration in [`mkdocs.yaml`](https://github.com/huangruiteng/loopx/blob/main/mkdocs.yaml) orchestrates these sources into a unified documentation site, with the "Public API" chapter extracting callable signatures from the source modules.

## Complete Working Example

```python
import loopx

def run_optimized_pipeline():
    """Demonstrate the complete LoopX API surface."""
    
    # 1. Observe current state

    status = loopx.status.get_status()
    if status["goal"]:
        print(f"Already running: {status['goal']}")
        return
    
    # 2. Verify resources

    if not loopx.quota.check_quota(resource="memory_gb", amount=8):
        raise RuntimeError("Insufficient memory quota")
    
    # 3. Launch goal

    result = loopx.runtime.start_goal(
        name="data-optimization",
        config={"description": "ETL pipeline optimization", "priority": 5}
    )
    
    # 4. Execute tasks

    loopx.runtime.run(task="extract", args=["source-db"])
    loopx.runtime.run(task="transform", args=["normalize-schema"])
    loopx.runtime.run(task="load", args=["warehouse"])
    
    return result["goal_id"]

if __name__ == "__main__":
    run_optimized_pipeline()

```

This example exercises all four core API areas in a realistic workflow, matching the patterns used by the LoopX CLI internally.

## Summary

- **LoopX API documentation** is delivered through the `loopx` Python package, not a REST endpoint.
- **Four stable modules** constitute the public surface: [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) (observation), [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py) (execution), [`loopx/quota.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/quota.py) (gating), and [`loopx/registry.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/registry.py) (extensions).
- **All state changes** must pass through these APIs; direct mutation of internal `loopx/state_*` modules is prohibited by design.
- **Version compatibility** is explicitly declared via `requires_loopx_api` pins, with 1.x stability guaranteed.
- **Documentation spans** MkDocs-generated sites, Markdown book chapters, and source docstrings for comprehensive coverage.

## Frequently Asked Questions

### Where is the LoopX API documentation hosted?

The LoopX API documentation is built locally from the repository using MkDocs ([`mkdocs.yaml`](https://github.com/huangruiteng/loopx/blob/main/mkdocs.yaml)). There is no centralized hosted version; users generate the HTML reference from the `docs/` directory. The source of truth remains the Python docstrings in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py), [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py), and related modules.

### How do I know if my code is using the stable LoopX API?

Check your imports. Stable API usage requires importing from top-level `loopx` submodules (`loopx.status`, `loopx.runtime`, etc.). Direct imports from `loopx.state_projection`, `loopx.state_refresh`, or other `state_*` modules indicate internal API usage that may break without notice.

### What is the LoopX API version compatibility guarantee?

LoopX follows semantic versioning for its API surface. The `requires_loopx_api = ">=1,<2"` declaration in [`docs/book/en/chapters/11-engineering-boundaries.md`](https://github.com/huangruiteng/loopx/blob/main/docs/book/en/chapters/11-engineering-boundaries.md) confirms that all 1.x releases maintain backward compatibility. Extensions must declare their required range; the runtime validates this on load.

### Can I use the LoopX API without the CLI?

Yes. The `loopx` CLI (`loopx doctor`, `loopx start-goal`) is a thin wrapper around the same Python API documented here. All CLI functionality is available programmatically through `loopx.runtime.start_goal()` and related functions, enabling headless automation and testing.