Skip to main content

​
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

CategoryDescription
Public EndpointsServer info, health checks, Swagger docs
AuthenticationLogin, logout, and JWT token management
WorkflowsList, view, and refresh workflows
RunsCreate and manage workflow executions
File UploadsUpload target files and workflows
SnapshotsExport and import workspace snapshots
WorkspacesList and manage workspaces
ArtifactsList and download output artifacts
AssetsView discovered assets
VulnerabilitiesView and manage vulnerabilities
Event LogsView execution event logs
Step ResultsQuery step execution results
FunctionsExecute and list utility functions
System StatisticsGet aggregated system stats
SettingsManage server configuration
DatabaseDatabase management and cleanup
InstallationInstall binaries and workflows
SchedulesManage scheduled workflows
Event ReceiverEvent-triggered workflows
Distributed ModeWorker and task management
LLM APILarge Language Model API
ReferenceError 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"}'