Skip to main content
Osmedeus provides a REST API for programmatic access.

Starting the Server

osmedeus server
Default: http://localhost:8002

Authentication

Get Token

curl -X POST http://localhost:8002/osm/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "osmedeus", "password": "osmedeus-admin"}'
Response:
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2024-01-16T14:30:00Z"
}

Use Token

Include in Authorization header:
curl http://localhost:8002/osm/api/workflows \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Default Credentials

Configure in osm-settings.yaml:
server:
  username: osmedeus
  password: [REDACTED:password]

API Documentation

Swagger UI available at: http://localhost:8002/swagger/

Public Endpoints

No authentication required:
MethodEndpointDescription
GET/healthHealth check
GET/health/readyReadiness probe
GET/server-infoServer version and info
GET/swagger/*API documentation

Endpoint Categories

Workflows

MethodEndpointDescription
GET/osm/api/workflowsList all workflows
GET/osm/api/workflows/:nameGet workflow details
GET/osm/api/workflows/tagsGet all workflow tags
POST/osm/api/workflows/refreshRefresh workflow index

Runs

MethodEndpointDescription
POST/osm/api/runsCreate and start a run
GET/osm/api/runsList runs
GET/osm/api/runs/:idGet run details
DELETE/osm/api/runs/:idCancel a run
GET/osm/api/runs/:id/stepsGet run steps
GET/osm/api/runs/:id/artifactsGet run artifacts

Schedules

MethodEndpointDescription
GET/osm/api/schedulesList schedules
POST/osm/api/schedulesCreate schedule
GET/osm/api/schedules/:idGet schedule
PUT/osm/api/schedules/:idUpdate schedule
DELETE/osm/api/schedules/:idDelete schedule
POST/osm/api/schedules/:id/enableEnable schedule
POST/osm/api/schedules/:id/disableDisable schedule
POST/osm/api/schedules/:id/triggerTrigger manually

Data

MethodEndpointDescription
GET/osm/api/workspacesList workspaces
GET/osm/api/assetsList assets
GET/osm/api/vulnerabilitiesList vulnerabilities
GET/osm/api/statsSystem statistics
GET/osm/api/event-logsEvent logs

Utilities

MethodEndpointDescription
POST/osm/api/functions/evalEvaluate function
GET/osm/api/functions/listList functions
POST/osm/api/upload-fileUpload file
POST/osm/api/workflow-uploadUpload workflow

Snapshots

MethodEndpointDescription
GET/osm/api/snapshotsList snapshots
POST/osm/api/snapshots/exportExport workspace
POST/osm/api/snapshots/importImport workspace
GET/osm/api/snapshots/download/:nameDownload snapshot

LLM (OpenAI-compatible)

MethodEndpointDescription
POST/osm/api/llm/v1/chat/completionsChat completion
POST/osm/api/llm/v1/embeddingsGenerate embeddings

Distributed (Master only)

MethodEndpointDescription
GET/osm/api/workersList workers
GET/osm/api/workers/:idWorker details
GET/osm/api/tasksList tasks
GET/osm/api/tasks/:idTask details
POST/osm/api/tasksSubmit task

Common Examples

Start a Scan

curl -X POST http://localhost:8002/osm/api/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "general",
    "target": "example.com",
    "params": {
      "threads": "50"
    }
  }'

List Runs

curl "http://localhost:8002/osm/api/runs?status=running&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Cancel Run

curl -X DELETE http://localhost:8002/osm/api/runs/run-123 \
  -H "Authorization: Bearer $TOKEN"

Query Assets

curl "http://localhost:8002/osm/api/assets?workspace=example.com&status_code=200" \
  -H "Authorization: Bearer $TOKEN"

Evaluate Function

curl -X POST http://localhost:8002/osm/api/functions/eval \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"script": "fileLength(\"/path/to/file\")"}'

Response Format

Success

{
  "data": { ... },
  "meta": {
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid target format"
  }
}

Pagination

For list endpoints:
curl "http://localhost:8002/osm/api/runs?offset=20&limit=10" \
  -H "Authorization: Bearer $TOKEN"
Parameters:
  • offset - Skip N records (default: 0)
  • limit - Max records to return (default: 20)

Detailed Documentation

For comprehensive API documentation with all request/response schemas:
  • Swagger UI: http://localhost:8002/swagger/
  • Detailed docs: ../api/

Next Steps