> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-management/reference/agent/rest-api.md).

# REST API

This page provides a reference for the Rumi Agent REST API.

## Base URL

```
http://<host>:<port>/rumi-agent
```

Default port: `7778`

## System Discovery

### List Systems

```
GET /v2/systems
```

Returns all managed systems with their containers, scripts, and configuration.

| Parameter         | Type            | Description              |
| ----------------- | --------------- | ------------------------ |
| `excludeInternal` | query (boolean) | Exclude internal systems |

### List System Names

```
GET /v2/systems/names
```

Returns only the names of available systems.

| Parameter         | Type            | Description              |
| ----------------- | --------------- | ------------------------ |
| `excludeInternal` | query (boolean) | Exclude internal systems |

## Script Execution

### List Scripts

```
GET /system/scripts
```

Returns available scripts for a system.

| Parameter    | Type           | Description            |
| ------------ | -------------- | ---------------------- |
| `systemName` | query (string) | System name (required) |

### Execute Script

```
POST /invoke/script
```

Executes a deployment script.

| Field | Type                        | Description                          |
| ----- | --------------------------- | ------------------------------------ |
| Body  | `InvokeSystemScriptRequest` | System name, script name, parameters |

**Response:** Execution UUID for tracking.

### Cancel Execution

```
POST /invoke/cancel
```

Cancels a running script execution.

| Parameter | Type           | Description              |
| --------- | -------------- | ------------------------ |
| `uuid`    | query (string) | Execution UUID to cancel |

## Application Command and Control

### List Commands

```
GET /app/commands
```

Returns available application commands across all deployed systems.

### Invoke Command

```
POST /app/command/invoke
```

Invokes an application command.

| Field | Type                      | Description                                  |
| ----- | ------------------------- | -------------------------------------------- |
| Body  | `InvokeAppCommandRequest` | Command name, target application, parameters |

## XAR Deployment

### Unpack XAR

```
POST /xars/unpack
```

Uploads and unpacks a XAR file, creating a new system.

## System Management

### Archive System

```
POST /v2/systems/archive
```

Archives a system, moving it to the `.archived/` directory.

### Restore System

```
POST /v2/systems/restore
```

Restores a previously archived system.

### Delete System

```
POST /v2/systems/delete
```

Permanently removes a system.

## Configuration

### Get Configuration

```
GET /v2/config
```

Returns the current Agent configuration.

### Update Configuration

```
POST /v2/config
```

Updates the Agent configuration.

## Health and Information

### Ping

```
GET /ping
```

Health check endpoint.

### Info

```
GET /info
```

Returns Agent version, status, and runtime information.

### Data Sources

```
GET /datasources
```

Returns available data sources (InfluxDB connection details).

## OpenAPI Specification

The Agent auto-generates an OpenAPI/Swagger 2.0 specification at build time:

```
target/classes/META-INF/openAPI/rumi-agent-api.yaml
```

This specification includes complete request/response schemas for all endpoints.