osmedeus/docs/api/reference.md

API Reference

Error Responses

All endpoints return errors in a consistent format:

{
  "error": true,
  "message": "Error description"
}

Common HTTP Status Codes:

• 200 - Success
• 201 - Created
• 202 - Accepted (async operation started)
• 400 - Bad Request (invalid input)
• 401 - Unauthorized (missing or invalid token)
• 404 - Not Found
• 500 - Internal Server Error

---

Pagination

Endpoints that return lists support pagination via query parameters:

Parameter	Default	Max	Description
offset	0	-	Number of records to skip
limit	20	10000	Maximum records to return

Example:

curl "http://localhost:8002/osm/api/assets?offset=100&limit=50" \
  -H "Authorization: Bearer $TOKEN"

---

Cron Expression Reference

Schedules use standard cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Examples:

• 0 2 * * * - Every day at 2:00 AM
• 0 0 * * 0 - Every Sunday at midnight
• */30 * * * * - Every 30 minutes
• 0 9-17 * * 1-5 - Every hour from 9 AM to 5 PM, Monday to Friday

---

Workflow Step Types

Reference documentation for workflow step types used in YAML workflow definitions.

bash

Execute shell commands on the local system or configured runner.

- name: run-nuclei
  type: bash
  log: "Running nuclei scan"
  command: nuclei -u {{Target}} -o {{Output}}/nuclei.txt
  timeout: 3600
  exports:
    nuclei_results: "{{Output}}/nuclei.txt"

Fields:

Field	Type	Required	Description
name	string	Yes	Unique step name
type	string	Yes	Must be bash
command	string	No*	Single command to execute
commands	array	No*	Sequential commands
parallel_commands	array	No*	Commands to run in parallel
timeout	int	No	Timeout in seconds
log	string	No	Log message displayed during execution
pre_condition	string	No	Condition that must be true to run
exports	map	No	Variables to export after execution

*One of command, commands, or parallel_commands is required.

---

function

Execute utility functions written in JavaScript via Otto VM.

- name: check-file
  type: function
  log: "Checking if results exist"
  function: fileExists("{{Output}}/results.txt")
  exports:
    has_results: "{{check_file_output}}"

Fields:

Field	Type	Required	Description
name	string	Yes	Unique step name
type	string	Yes	Must be function
function	string	No*	Single function to execute
functions	array	No*	Sequential functions
parallel_functions	array	No*	Functions to run in parallel

*One of function, functions, or parallel_functions is required.

---

parallel-steps

Run multiple steps concurrently.

- name: parallel-scans
  type: parallel-steps
  log: "Running scans in parallel"
  parallel_steps:
    - name: nuclei-scan
      type: bash
      command: nuclei -u {{Target}}
    - name: httpx-scan
      type: bash
      command: httpx -u {{Target}}

Fields:

Field	Type	Required	Description
name	string	Yes	Unique step name
type	string	Yes	Must be parallel-steps
parallel_steps	array	Yes	Array of steps to run concurrently

---

foreach

Iterate over items from a file or array.

- name: scan-subdomains
  type: foreach
  log: "Scanning each subdomain"
  input: "{{Output}}/subdomains.txt"
  variable: subdomain
  step:
    name: scan-subdomain
    type: bash
    command: httpx -u [[subdomain]]

Fields:

Field	Type	Required	Description
name	string	Yes	Unique step name
type	string	Yes	Must be foreach
input	string	Yes	File path or array to iterate over
variable	string	Yes	Loop variable name (use [[variable]])
step	object	Yes	Step to execute for each item
parallel	int	No	Number of parallel iterations

---

remote-bash

Execute commands in Docker containers or via SSH.

- name: docker-scan
  type: remote-bash
  log: "Running scan in Docker"
  step_runner: docker
  step_runner_config:
    image: "projectdiscovery/nuclei:latest"
    volumes:
      - "{{Output}}:/output"
  command: nuclei -u {{Target}} -o /output/nuclei.txt

Fields:

Field	Type	Required	Description
name	string	Yes	Unique step name
type	string	Yes	Must be remote-bash
step_runner	string	Yes	docker or ssh
step_runner_config	object	No	Runner-specific configuration
command	string	No*	Command to execute
commands	array	No*	Sequential commands

Docker Configuration:

step_runner_config:
  image: "image:tag"
  volumes: ["host:container"]
  env:
    KEY: value
  network: "host"
  workdir: "/app"

SSH Configuration:

step_runner_config:
  host: "worker.example.com"
  user: "ubuntu"
  key_file: "~/.ssh/id_rsa"
  port: 22

---

http

Make HTTP requests and capture responses.

- name: api-request
  type: http
  log: "Calling API"
  url: "https://api.example.com/endpoint"
  method: POST
  headers:
    Content-Type: "application/json"
    Authorization: "Bearer {{api_token}}"
  request_body: '{"domain": "{{Target}}"}'
  timeout: 30
  exports:
    api_response: "{{api_request_body}}"

Fields:

Field	Type	Required	Description
name	string	Yes	Unique step name
type	string	Yes	Must be http
url	string	Yes	Request URL
method	string	No	HTTP method (default: GET)
headers	map	No	Request headers
request_body	string	No	Request body for POST/PUT
timeout	int	No	Timeout in seconds

Auto-Exports:

• <step_name>_status_code - HTTP status code
• <step_name>_body - Response body
• <step_name>_headers - Response headers

---

llm

Execute LLM (Large Language Model) API calls for AI-powered analysis.

- name: analyze-target
  type: llm
  log: "Analyzing target with LLM"
  messages:
    - role: system
      content: "You are a security analyst."
    - role: user
      content: "Analyze the security of {{Target}}"
  llm_config:
    max_tokens: 1000
    temperature: 0.7
  timeout: 60
  exports:
    analysis: "{{analyze_target_content}}"

Fields:

Field	Type	Required	Description
name	string	Yes	Unique step name
type	string	Yes	Must be llm
messages	array	No*	Chat messages (role + content)
is_embedding	bool	No	Set to true for embeddings
embedding_input	array	No*	Strings to embed
llm_config	object	No	Step-level LLM configuration
tools	array	No	Tool definitions for function calling
tool_choice	string	No	Tool selection (auto, none, etc.)
extra_llm_parameters	map	No	Additional provider-specific params
timeout	int	No	Timeout in seconds

*Either messages or embedding_input (with is_embedding: true) is required.

Message Format:

messages:
  - role: system
    content: "System prompt"
  - role: user
    content: "User message with {{variables}}"

Multimodal Messages (with images):

messages:
  - role: user
    content:
      - type: text
        text: "What do you see in this screenshot?"
      - type: image_url
        image_url:
          url: "data:image/png;base64,{{screenshot_base64}}"

LLM Configuration Override:

llm_config:
  model: "gpt-4"
  max_tokens: 2000
  temperature: 0.3
  response_format:
    type: json_object

Embeddings:

- name: generate-embeddings
  type: llm
  is_embedding: true
  embedding_input:
    - "{{Target}} security analysis"
    - "vulnerability assessment"
  exports:
    embeddings: "{{generate_embeddings_llm_resp}}"

Tool Calling:

- name: with-tools
  type: llm
  messages:
    - role: user
      content: "What DNS records exist for {{Target}}?"
  tools:
    - type: function
      function:
        name: dns_lookup
        description: "Look up DNS records"
        parameters:
          type: object
          properties:
            domain:
              type: string
          required: [domain]
  tool_choice: auto

Auto-Exports:

• <step_name>_llm_resp - Full response object (id, model, usage, content, tool_calls)
• <step_name>_content - Just the content string for easy access