osmedeus/docs/api

Osmedeus API Documentation

Overview

The Osmedeus API provides a RESTful interface for managing security automation workflows, runs, and distributed task execution.

Base URL: http://localhost:8002

Default Port: 8002

Authentication

Most API endpoints require authentication. Two methods are supported:

1. JWT Token: Obtain a token via the login endpoint, then include it in requests using the Authorization: Bearer <token> header.

2. API Key: Use a static API key via the x-osm-api-key header. Configure in ~/osmedeus-base/osm-settings.yaml under server.auth_api_key.

See Authentication for details.

API Reference

Category	Description
Public Endpoints	Server info, health checks, Swagger docs
Authentication	Login and JWT token management
Workflows	List, view, and refresh workflows
Runs	Create and manage workflow executions
File Uploads	Upload target files and workflows
Snapshots	Download workspace snapshots
Workspaces	List and manage workspaces
Assets	View discovered assets
Vulnerabilities	View and manage vulnerabilities
Event Logs	View execution event logs
Step Results	Query step execution results
Functions	Execute and list utility functions
System Statistics	Get aggregated system stats
Settings	Manage server configuration
Installation	Install binaries and workflows
Schedules	Manage scheduled workflows
Distributed Mode	Worker and task management
LLM API	Large Language Model API
Reference	Error codes, pagination, cron expressions, step types

Quick Start

# Get server info (no auth required)
curl http://localhost:8002/server-info

# Login and get token
export TOKEN=$(curl -s -X POST http://localhost:8002/osm/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "osmedeus", "password": "admin"}' | jq -r '.token')

# List workflows
curl http://localhost:8002/osm/api/workflows \
  -H "Authorization: Bearer $TOKEN"

# Start a scan
curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"flow": "subdomain-enum", "target": "example.com"}'