REST API Reference

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

osmedeus server --port 8080

Authentication

All endpoints require bearer token authentication:

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.

POST /osm/api/runs

Request Body:

{
  "workflow": "general",
  "target": "example.com",
  "params": {
    "threads": "20"
  }
}

Response:

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

List Runs

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

GET /osm/api/runs/:run_id

Get Run Steps

GET /osm/api/runs/:run_id/steps

Get Run Artifacts

GET /osm/api/runs/:run_id/artifacts

Cancel Run

POST /osm/api/runs/:run_id/cancel

Workflows

List Workflows

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:

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

Get Workflow

GET /osm/api/workflows/:name

Get Workflow Tags

Get all unique tags from indexed workflows.

GET /osm/api/workflows/tags

Response:

{
  "tags": ["recon", "subdomain", "fast", "vuln", "scan"],
  "count": 5
}

Refresh Workflow Index

Re-index all workflows from filesystem to database.

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:

{
  "message": "Workflows indexed successfully",
  "added": 5,
  "updated": 2,
  "removed": 1,
  "errors": []
}

Schedules

List Schedules

GET /osm/api/schedules

Create Schedule

POST /osm/api/schedules

Request Body:

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

Get Schedule

GET /osm/api/schedules/:id

Update Schedule

PUT /osm/api/schedules/:id

Delete Schedule

DELETE /osm/api/schedules/:id

Enable/Disable Schedule

POST /osm/api/schedules/:id/enable
POST /osm/api/schedules/:id/disable

Trigger Schedule

Execute a scheduled workflow immediately.

POST /osm/api/schedules/:id/trigger

Assets

List Assets

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

GET /osm/api/assets/:id

Asset Diff

Compare assets between two time points to identify changes.

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:

{
  "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

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

GET /osm/api/vulnerabilities/:id

Vulnerability Diff

Compare vulnerabilities between two time points.

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:

{
  "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

GET /osm/api/workspaces

Get Workspace

GET /osm/api/workspaces/:name

Delete Workspace

DELETE /osm/api/workspaces/:name

Functions

Execute Function

Execute a utility function.

POST /osm/api/functions/execute

Request Body:

{
  "expression": "fileLength('{{Output}}/subdomains.txt')",
  "context": {
    "Output": "/workspaces/example_com"
  }
}

Response:

{
  "data": {
    "result": 1234
  }
}

List Functions

GET /osm/api/functions
GET /osm/api/functions?category=file

Snapshots

List Snapshots

GET /osm/api/snapshots

Export Snapshot

POST /osm/api/snapshots/export

Request Body:

{
  "workspace": "example_com",
  "include_artifacts": true
}

Import Snapshot

POST /osm/api/snapshots/import

Upload a snapshot ZIP file.

LLM

Chat Completions

OpenAI-compatible chat completions endpoint.

POST /osm/api/llm/chat/completions

Request Body:

{
  "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

POST /osm/api/llm/embeddings

Request Body:

{
  "model": "text-embedding-ada-002",
  "input": ["text to embed"]
}

Install

List Binary Registry

GET /osm/api/install/registry
GET /osm/api/install/registry?method=nix
GET /osm/api/install/registry?method=direct

Check Binary Status

GET /osm/api/install/status/:binary_name

Install Binary

POST /osm/api/install/binary

Request Body:

{
  "name": "nuclei",
  "method": "nix"
}

Event Logs

List Events

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.

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:

{
  "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

GET /osm/api/health

Response:

{
  "status": "healthy",
  "version": "5.0.0",
  "database": "connected",
  "workflows_loaded": 42
}

Error Responses

All error responses follow this format:

{
  "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

Getting Started

Advanced Usage

Understand Architecture

Workflows

Functions

Cloud

Advanced Topics & Extending Osmedeus

Reference

Documentation Index

​REST API Reference

​Authentication

​Endpoints Overview

​Runs

​Create Run

​List Runs

​Get Run

​Get Run Steps

​Get Run Artifacts

​Cancel Run

​Workflows

​List Workflows

​Get Workflow

​Get Workflow Tags

​Refresh Workflow Index

​Schedules

​List Schedules

​Create Schedule

​Get Schedule

​Update Schedule

​Delete Schedule

​Enable/Disable Schedule

​Trigger Schedule

​Assets

​List Assets

​Get Asset

​Asset Diff

​Vulnerabilities

​List Vulnerabilities

​Get Vulnerability

​Vulnerability Diff

​Workspaces

​List Workspaces

​Get Workspace

​Delete Workspace

​Functions

​Execute Function

​List Functions

​Snapshots

​List Snapshots

​Export Snapshot

​Import Snapshot

​LLM

​Chat Completions

​Embeddings

​Install

​List Binary Registry

​Check Binary Status

​Install Binary

​Event Logs

​List Events

​Step Results

​List Step Results

​Health

​Health Check

​Error Responses

REST API Reference

Authentication

Endpoints Overview

Runs

Create Run

List Runs

Get Run

Get Run Steps

Get Run Artifacts

Cancel Run

Workflows

List Workflows

Get Workflow

Get Workflow Tags

Refresh Workflow Index

Schedules

List Schedules

Create Schedule

Get Schedule

Update Schedule

Delete Schedule

Enable/Disable Schedule

Trigger Schedule

Assets

List Assets

Get Asset

Asset Diff

Vulnerabilities

List Vulnerabilities

Get Vulnerability

Vulnerability Diff

Workspaces

List Workspaces

Get Workspace

Delete Workspace

Functions

Execute Function

List Functions

Snapshots

List Snapshots

Export Snapshot

Import Snapshot

LLM

Chat Completions

Embeddings

Install

List Binary Registry

Check Binary Status

Install Binary

Event Logs

List Events

Step Results

List Step Results

Health

Health Check

Error Responses