> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osmedeus.org/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Reference

> Complete REST API reference for the Osmedeus server

# REST API Reference

The Osmedeus server provides a REST API for managing workflows, runs, and assets. Start the server with:

```bash theme={null}
osmedeus server --port 8080
```

## Authentication

All endpoints require bearer token authentication:

```bash theme={null}
curl -H "Authorization: Bearer <your_token>" http://localhost:8080/osm/api/...
```

## Endpoints Overview

| Category        | Base Path                  | Description                  |
| --------------- | -------------------------- | ---------------------------- |
| Runs            | `/osm/api/runs`            | Manage workflow executions   |
| Workflows       | `/osm/api/workflows`       | List and query workflows     |
| Schedules       | `/osm/api/schedules`       | Manage scheduled triggers    |
| Assets          | `/osm/api/assets`          | Query discovered assets      |
| Vulnerabilities | `/osm/api/vulnerabilities` | Query vulnerabilities        |
| Workspaces      | `/osm/api/workspaces`      | Manage workspaces            |
| Functions       | `/osm/api/functions`       | Execute utility functions    |
| Snapshots       | `/osm/api/snapshots`       | Export/import workspaces     |
| LLM             | `/osm/api/llm`             | LLM chat/embeddings          |
| Install         | `/osm/api/install`         | Binary management            |
| Step Results    | `/osm/api/step-results`    | Query step execution results |

***

## Runs

### Create Run

Start a new workflow execution.

```bash theme={null}
POST /osm/api/runs
```

**Request Body:**

```json theme={null}
{
  "workflow": "general",
  "target": "example.com",
  "params": {
    "threads": "20"
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "run_id": "run-abc123",
    "status": "running",
    "workflow": "general",
    "target": "example.com",
    "started_at": "2025-01-15T10:00:00Z"
  }
}
```

### List Runs

```bash theme={null}
GET /osm/api/runs
GET /osm/api/runs?status=running
GET /osm/api/runs?workspace=example_com
```

**Query Parameters:**

| Parameter   | Description                                            |
| ----------- | ------------------------------------------------------ |
| `status`    | Filter by status (pending, running, completed, failed) |
| `workspace` | Filter by workspace name                               |
| `limit`     | Maximum results (default: 50)                          |
| `offset`    | Pagination offset                                      |

### Get Run

```bash theme={null}
GET /osm/api/runs/:run_id
```

### Get Run Steps

```bash theme={null}
GET /osm/api/runs/:run_id/steps
```

### Get Run Artifacts

```bash theme={null}
GET /osm/api/runs/:run_id/artifacts
```

### Cancel Run

```bash theme={null}
POST /osm/api/runs/:run_id/cancel
```

***

## Workflows

### List Workflows

```bash theme={null}
GET /osm/api/workflows
GET /osm/api/workflows?kind=module
GET /osm/api/workflows?tags=recon,fast
```

**Query Parameters:**

| Parameter | Description                             |
| --------- | --------------------------------------- |
| `kind`    | Filter by kind (module, flow, fragment) |
| `tags`    | Filter by tags (comma-separated)        |

**Response:**

```json theme={null}
{
  "data": [
    {
      "name": "subdomain-enum",
      "kind": "module",
      "description": "Enumerate subdomains",
      "tags": ["recon", "subdomain"],
      "params": [
        {"name": "threads", "default": "10", "required": false}
      ]
    }
  ]
}
```

### Get Workflow

```bash theme={null}
GET /osm/api/workflows/:name
```

### Get Workflow Tags

Get all unique tags from indexed workflows.

```bash theme={null}
GET /osm/api/workflows/tags
```

**Response:**

```json theme={null}
{
  "tags": ["recon", "subdomain", "fast", "vuln", "scan"],
  "count": 5
}
```

### Refresh Workflow Index

Re-index all workflows from filesystem to database.

```bash theme={null}
POST /osm/api/workflows/refresh
POST /osm/api/workflows/refresh?force=true
```

**Query Parameters:**

| Parameter | Required | Description                                         |
| --------- | -------- | --------------------------------------------------- |
| `force`   | No       | Force re-index all workflows regardless of checksum |

**Response:**

```json theme={null}
{
  "message": "Workflows indexed successfully",
  "added": 5,
  "updated": 2,
  "removed": 1,
  "errors": []
}
```

***

## Schedules

### List Schedules

```bash theme={null}
GET /osm/api/schedules
```

### Create Schedule

```bash theme={null}
POST /osm/api/schedules
```

**Request Body:**

```json theme={null}
{
  "name": "daily-scan",
  "workflow": "general",
  "target": "example.com",
  "trigger_type": "cron",
  "schedule": "0 2 * * *",
  "enabled": true,
  "params": {
    "threads": "10"
  }
}
```

### Get Schedule

```bash theme={null}
GET /osm/api/schedules/:id
```

### Update Schedule

```bash theme={null}
PUT /osm/api/schedules/:id
```

### Delete Schedule

```bash theme={null}
DELETE /osm/api/schedules/:id
```

### Enable/Disable Schedule

```bash theme={null}
POST /osm/api/schedules/:id/enable
POST /osm/api/schedules/:id/disable
```

### Trigger Schedule

Execute a scheduled workflow immediately.

```bash theme={null}
POST /osm/api/schedules/:id/trigger
```

***

## Assets

### List Assets

```bash theme={null}
GET /osm/api/assets
GET /osm/api/assets?workspace=example_com
GET /osm/api/assets?asset_type=subdomain
GET /osm/api/assets?status_code=200
```

**Query Parameters:**

| Parameter     | Description                               |
| ------------- | ----------------------------------------- |
| `workspace`   | Filter by workspace                       |
| `asset_type`  | Filter by type (subdomain, url, ip, etc.) |
| `status_code` | Filter by HTTP status code                |
| `limit`       | Maximum results (default: 100)            |
| `offset`      | Pagination offset                         |

### Get Asset

```bash theme={null}
GET /osm/api/assets/:id
```

### Asset Diff

Compare assets between two time points to identify changes.

```bash theme={null}
GET /osm/api/assets/diff?workspace=example_com&from=2025-01-01T00:00:00Z&to=2025-01-15T00:00:00Z
```

**Query Parameters:**

| Parameter   | Required | Description                            |
| ----------- | -------- | -------------------------------------- |
| `workspace` | Yes      | Workspace name                         |
| `from`      | Yes      | Start time (RFC3339 or Unix timestamp) |
| `to`        | No       | End time (default: now)                |

**Supported Time Formats:**

* RFC3339: `2025-01-15T10:00:00Z`
* Unix timestamp: `1705312800`
* Date only: `2025-01-15`
* DateTime: `2025-01-15 10:00:00`

**Response:**

```json theme={null}
{
  "data": {
    "workspace_name": "example_com",
    "from_time": "2025-01-01T00:00:00Z",
    "to_time": "2025-01-15T00:00:00Z",
    "added": [
      {
        "id": 123,
        "asset_value": "new.example.com",
        "asset_type": "subdomain",
        "url": "https://new.example.com",
        "status_code": 200,
        "created_at": "2025-01-10T12:00:00Z"
      }
    ],
    "removed": [
      {
        "id": 45,
        "asset_value": "old.example.com",
        "asset_type": "subdomain",
        "last_seen_at": "2024-12-20T00:00:00Z"
      }
    ],
    "changed": [
      {
        "asset_id": 67,
        "asset_value": "api.example.com",
        "url": "https://api.example.com",
        "changes": [
          {
            "field": "status_code",
            "old_value": 200,
            "new_value": 301
          }
        ]
      }
    ],
    "summary": {
      "total_added": 5,
      "total_removed": 2,
      "total_changed": 3
    }
  }
}
```

***

## Vulnerabilities

### List Vulnerabilities

```bash theme={null}
GET /osm/api/vulnerabilities
GET /osm/api/vulnerabilities?workspace=example_com
GET /osm/api/vulnerabilities?severity=critical
```

**Query Parameters:**

| Parameter     | Description                                            |
| ------------- | ------------------------------------------------------ |
| `workspace`   | Filter by workspace                                    |
| `severity`    | Filter by severity (critical, high, medium, low, info) |
| `asset_value` | Filter by asset                                        |
| `limit`       | Maximum results (default: 100)                         |
| `offset`      | Pagination offset                                      |

### Get Vulnerability

```bash theme={null}
GET /osm/api/vulnerabilities/:id
```

### Vulnerability Diff

Compare vulnerabilities between two time points.

```bash theme={null}
GET /osm/api/vulnerabilities/diff?workspace=example_com&from=2025-01-01T00:00:00Z
```

**Query Parameters:**

| Parameter   | Required | Description                            |
| ----------- | -------- | -------------------------------------- |
| `workspace` | Yes      | Workspace name                         |
| `from`      | Yes      | Start time (RFC3339 or Unix timestamp) |
| `to`        | No       | End time (default: now)                |

**Response:**

```json theme={null}
{
  "data": {
    "workspace_name": "example_com",
    "from_time": "2025-01-01T00:00:00Z",
    "to_time": "2025-01-15T00:00:00Z",
    "added": [
      {
        "id": 789,
        "vuln_info": "CVE-2025-1234",
        "asset_value": "api.example.com",
        "severity": "critical",
        "template_id": "CVE-2025-1234",
        "created_at": "2025-01-12T08:00:00Z"
      }
    ],
    "removed": [],
    "changed": [],
    "summary": {
      "total_added": 1,
      "total_removed": 0,
      "total_changed": 0
    }
  }
}
```

***

## Workspaces

### List Workspaces

```bash theme={null}
GET /osm/api/workspaces
```

### Get Workspace

```bash theme={null}
GET /osm/api/workspaces/:name
```

### Delete Workspace

```bash theme={null}
DELETE /osm/api/workspaces/:name
```

***

## Functions

### Execute Function

Execute a utility function.

```bash theme={null}
POST /osm/api/functions/execute
```

**Request Body:**

```json theme={null}
{
  "expression": "fileLength('{{Output}}/subdomains.txt')",
  "context": {
    "Output": "/workspaces/example_com"
  }
}
```

**Response:**

```json theme={null}
{
  "data": {
    "result": 1234
  }
}
```

### List Functions

```bash theme={null}
GET /osm/api/functions
GET /osm/api/functions?category=file
```

***

## Snapshots

### List Snapshots

```bash theme={null}
GET /osm/api/snapshots
```

### Export Snapshot

```bash theme={null}
POST /osm/api/snapshots/export
```

**Request Body:**

```json theme={null}
{
  "workspace": "example_com",
  "include_artifacts": true
}
```

### Import Snapshot

```bash theme={null}
POST /osm/api/snapshots/import
```

Upload a snapshot ZIP file.

***

## LLM

### Chat Completions

OpenAI-compatible chat completions endpoint.

```bash theme={null}
POST /osm/api/llm/chat/completions
```

**Request Body:**

```json theme={null}
{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a security analyst."},
    {"role": "user", "content": "Analyze this finding..."}
  ],
  "temperature": 0.7,
  "max_tokens": 2000
}
```

### Embeddings

```bash theme={null}
POST /osm/api/llm/embeddings
```

**Request Body:**

```json theme={null}
{
  "model": "text-embedding-ada-002",
  "input": ["text to embed"]
}
```

***

## Install

### List Binary Registry

```bash theme={null}
GET /osm/api/install/registry
GET /osm/api/install/registry?method=nix
GET /osm/api/install/registry?method=direct
```

### Check Binary Status

```bash theme={null}
GET /osm/api/install/status/:binary_name
```

### Install Binary

```bash theme={null}
POST /osm/api/install/binary
```

**Request Body:**

```json theme={null}
{
  "name": "nuclei",
  "method": "nix"
}
```

***

## Event Logs

### List Events

```bash theme={null}
GET /osm/api/events
GET /osm/api/events?topic=assets.new
GET /osm/api/events?run_id=run-abc123
```

**Query Parameters:**

| Parameter | Description           |
| --------- | --------------------- |
| `topic`   | Filter by event topic |
| `run_id`  | Filter by run ID      |
| `from`    | Start time filter     |
| `to`      | End time filter       |
| `limit`   | Maximum results       |

***

## Step Results

### List Step Results

Query step execution results with filtering and pagination.

```bash theme={null}
GET /osm/api/step-results
GET /osm/api/step-results?workspace=example_com
GET /osm/api/step-results?status=completed
GET /osm/api/step-results?run_id=123
```

**Query Parameters:**

| Parameter   | Description                                            |
| ----------- | ------------------------------------------------------ |
| `workspace` | Filter by workspace name                               |
| `status`    | Filter by status (pending, running, completed, failed) |
| `step_type` | Filter by step type (bash, function, etc.)             |
| `run_id`    | Filter by run ID                                       |
| `offset`    | Pagination offset (default: 0)                         |
| `limit`     | Maximum results (default: 20, max: 10000)              |

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": 123,
      "step_name": "subfinder",
      "step_type": "bash",
      "status": "completed",
      "run_id": 456,
      "workspace": "example_com",
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:05:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}
```

***

## Health

### Health Check

```bash theme={null}
GET /osm/api/health
```

**Response:**

```json theme={null}
{
  "status": "healthy",
  "version": "5.0.0",
  "database": "connected",
  "workflows_loaded": 42
}
```

***

## Error Responses

All error responses follow this format:

```json theme={null}
{
  "error": true,
  "message": "Error description"
}
```

Common HTTP status codes:

| Code | Description                             |
| ---- | --------------------------------------- |
| 400  | Bad Request - Invalid parameters        |
| 401  | Unauthorized - Missing or invalid token |
| 404  | Not Found - Resource doesn't exist      |
| 500  | Internal Server Error - Server error    |