# How to Integrate Modly with Other Services via the REST API

> Integrate Modly with other services using its powerful FastAPI REST API. Submit jobs, manage workflows, and control functionality via standard HTTP endpoints for seamless integration.

- Repository: [lightningpixel/modly](https://github.com/lightningpixel/modly)
- Tags: how-to-guide
- Published: 2026-08-19

---

**Yes, Modly exposes a comprehensive FastAPI-based REST API that allows external services to submit generation jobs, manage workflows, and control core functionality through standard HTTP endpoints with JSON responses and Server-Sent Events (SSE) streaming.**

Modly (from the `lightningpixel/modly` repository) provides a full-featured HTTP interface for integrating with external pipelines. The API follows REST conventions and delegates to a service layer abstraction, making it straightforward to connect automation scripts, web applications, or third-party tools to Modly's 3D generation capabilities.

## API Architecture and Available Endpoints

The Modly API is built on **FastAPI** and organizes functionality into dedicated routers under the `/api/v1` base path. Each router handles a specific domain of the application:

- **Generation** ([`api/routers/generation.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/generation.py)): Exposes `/api/v1/generation` endpoints for submitting prompts, streaming results, and retrieving generation metadata.
- **Workflow Runs** ([`api/routers/workflow_runs.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/workflow_runs.py)): Manages execution lifecycles via `/api/v1/workflow-runs` for operations like mesh repair and mesh smoothing.
- **Model Management** ([`api/routers/model.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/model.py)): Provides `/api/v1/model` endpoints for listing available models, downloading weights, and setting active configurations.
- **Settings** ([`api/routers/settings.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/settings.py)): Controls Modly configuration through `/api/v1/settings`, including GPU allocation and temporary directory paths.
- **Extensions** ([`api/routers/extensions.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/extensions.py)): Handles third-party extension lifecycle via `/api/v1/extensions` for installation and updates.
- **Optimization** ([`api/routers/optimize.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/optimize.py)): Triggers model-specific optimizations like quantization at `/api/v1/optimize`.
- **Export** ([`api/routers/export.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/export.py)): Retrieves generated assets including meshes, textures, and UV maps from `/api/v1/export`.
- **Status & Health** ([`api/routers/status.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/status.py)): Reports server health, version, and uptime at `/api/v1/status`.
- **Agent** ([`api/routers/agent.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/agent.py)): Provides remote control of the Modly CLI agent process through `/api/v1/agent` endpoints.

All routes return **JSON** responses, with **Server-Sent Events (SSE)** available for streaming generation output in real time.

## Authentication and Security

The API supports optional authentication via **Bearer tokens**. Clients must supply the API key in the `Authorization` header using the format `Authorization: Bearer <token>`. Keys are stored in Modly's internal settings and can be generated through the web interface or programmatically via the `/api/v1/settings` endpoint. When authentication is enabled, all requests to protected endpoints must include this header.

## Integration Workflow

External services interact with Modly through a standard four-phase pattern:

1. **Discover capabilities**: Query `/api/v1/status` or `/api/v1/model` to enumerate available models and extensions before submitting work.
2. **Submit work**: POST generation payloads to `/api/v1/generation` or workflow configurations to `/api/v1/workflow-runs` to initiate processing.
3. **Track progress**: Poll the specific job ID endpoint (e.g., `/api/v1/generation/{job_id}`) or consume the SSE stream for live updates during long-running operations.
4. **Retrieve results**: Download final artifacts via `/api/v1/export/{job_id}` or access the filesystem paths returned in the completion response.

The separation between the router layer (`api/routers/`) and the service layer (`api/services/`) ensures that underlying implementations (such as model runners or extension handlers) can be swapped without breaking the external contract.

## Implementation Examples

### Python Client Implementation

The following Python script demonstrates submitting a prompt with SSE streaming using the `requests` library:

```python
import requests

API_URL = "http://localhost:8000/api/v1/generation"
HEADERS = {"Authorization": "Bearer your_api_key"}

payload = {
    "model": "stable-diffusion-v1-5",
    "prompt": "A futuristic cityscape at sunset",
    "negative_prompt": "",
    "steps": 30,
    "cfg_scale": 7.5,
    "width": 512,
    "height": 512,
    "stream": True,               # Ask for SSE streaming

}

# Initiate the generation; the response contains a job_id

resp = requests.post(API_URL, json=payload, headers=HEADERS, stream=True)

for line in resp.iter_lines():
    if line:
        # Each line is a JSON chunk with partial output

        data = line.decode("utf-8")
        print("Update:", data)

```

### JavaScript Fetch API

This example triggers a mesh-repair workflow using modern JavaScript `fetch`:

```javascript
const apiBase = "http://localhost:8000/api/v1";
const apiKey = "your_api_key";

async function startRepair(meshUrl) {
  const response = await fetch(`${apiBase}/workflow-runs`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      workflow: "mesh-repair",
      inputs: { mesh: meshUrl }
    })
  });

  const { job_id } = await response.json();
  console.log("Workflow started – job ID:", job_id);
  // Poll for status
  const status = await fetch(`${apiBase}/workflow-runs/${job_id}`);
  console.log(await status.json());
}

```

### Command Line with cURL

To list installed extensions from the terminal:

```bash
curl -H "Authorization: Bearer $MODLY_API_KEY" \
     http://localhost:8000/api/v1/extensions

```

## Core Implementation Files

Understanding these source files helps when debugging or extending the API:

- **[`api/main.py`](https://github.com/lightningpixel/modly/blob/main/api/main.py)**: The FastAPI application entry point that registers all routers and middleware.
- **[`api/routers/generation.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/generation.py)**: Implements `/generation` endpoints including SSE streaming logic.
- **[`api/routers/workflow_runs.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/workflow_runs.py)**: Handles workflow execution state machines for operations like mesh repair.
- **[`api/services/generator_registry.py`](https://github.com/lightningpixel/modly/blob/main/api/services/generator_registry.py)**: Central registry for model and extension discovery consumed by the API layer.
- **[`api/services/extension_process.py`](https://github.com/lightningpixel/modly/blob/main/api/services/extension_process.py)**: Manages spawning and monitoring of external extension processes.
- **[`api/schemas/generation.py`](https://github.com/lightningpixel/modly/blob/main/api/schemas/generation.py)**: Contains **Pydantic** models defining request and response validation for generation endpoints.

## Summary

- Modly provides a **FastAPI-based REST API** under `/api/v1` with standardized JSON responses.
- Nine specialized routers cover generation, workflows, models, settings, extensions, optimization, export, status, and agent control.
- Authentication uses optional **Bearer tokens** via the `Authorization` header.
- Both polling and **Server-Sent Events (SSE)** are supported for job progress monitoring.
- Any HTTP-capable client (Python, JavaScript, curl, etc.) can integrate with Modly's service layer abstractions.

## Frequently Asked Questions

### Does Modly require authentication for API access?

No, authentication is optional. When enabled, clients must include a valid API key in the `Authorization: Bearer <token>` header. The key can be generated through the Modly UI or via the `/api/v1/settings` endpoint according to the `lightningpixel/modly` source code.

### What response formats does the Modly API support?

All endpoints return **JSON** responses for standard requests. For generation tasks, the API supports **Server-Sent Events (SSE)** streams when the `stream` parameter is set to `true`, allowing real-time progress updates as implemented in [`api/routers/generation.py`](https://github.com/lightningpixel/modly/blob/main/api/routers/generation.py).

### Can external services monitor job progress in real-time?

Yes, services can either poll the specific job endpoint (such as `/api/v1/generation/{job_id}`) or consume the SSE stream opened during the initial POST request. The SSE approach provides lower latency updates for long-running 3D generation workflows.

### Is the Modly API compatible with OpenAPI or Swagger documentation?

Because Modly uses **FastAPI**, it automatically generates an OpenAPI schema and interactive documentation. You can access the Swagger UI at `/docs` or the ReDoc interface at `/redoc` when the server is running, as defined in [`api/main.py`](https://github.com/lightningpixel/modly/blob/main/api/main.py).