Skip to content

Security.RunDevelopers

v1 PreviewOpenAPI ↗

API & MCP reference/Submit a tool run

HTTP REFERENCE

Submit a tool run

Submit a native invocation. HTTP 202 means accepted; follow the run for actual execution and cleanup.

View as Markdown ↗

POST/v1/tool-runs

Start the tool with your inputs

Choose a tool, map sealed artifact IDs to paths, and pass its native command arguments in invocation.

What to do next

Save the returned run ID. A 202 response means accepted; poll the run or its events for execution results.

Read the step-by-step guide →

Send an Idempotency-Key. Keep the same key and body when retrying this operation.

Parameter and response reference

Parameters

authorizationheader · string | nullrequired

idempotency-keyheader · string | nullrequired

Request body

toolstring

Tool

Default: "yara"

operationstring | null

Operation

versionstring | null

Version

inputsYaraInputs | null

Show child parameters

artifact_idstringrequired

Artifact Id

Pattern: "^artifact_[a-f0-9]{32}$"

rules_artifact_idstring | null

Rules Artifact Id

invocationNativeInvocation | null

Show child parameters

executablestring | null

Executable

argsarray of string

Args

Max items: 256

filesarray of NativeFile

Files

Max items: 64

Show child parameters

pathstringrequired

Path

artifact_idstringrequired

Artifact Id

Pattern: "^artifact_[a-f0-9]{32}$"

executableboolean

Executable

Default: false

empty_filesarray of string

Empty Files

Max items: 64

directoriesarray of string

Directories

Max items: 64

stdin_artifact_idstring | null

Stdin Artifact Id

environmentobject

Environment

working_directorystring

Working Directory

Default: "."

outputsarray of string

Outputs

Max items: 64

success_exit_codesarray of integer

Success Exit Codes

Max items: 16

timeout_secondsinteger

Timeout Seconds

Default: 30 · Minimum: 1.0 · Maximum: 120.0

target_profilestring | null

Target Profile

Responses

202 Successful Response
422 Validation Error

Copyable examples · your API endpoint

Request

curl -X POST "$SECURITY_RUN_URL/v1/tool-runs" \
  -H "Authorization: Bearer $SECURITY_RUN_API_KEY" \
  -H "Idempotency-Key: unique-request-key" \
  -H "Content-Type: application/json" \
  --data '{"tool": "yara", "timeout_seconds": 30, "invocation": {"executable": "yara", "args": ["-s", "rules.yar", "sample.txt"], "files": [{"path": "rules.yar", "artifact_id": "artifact_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}, {"path": "sample.txt", "artifact_id": "artifact_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}]}}'

Request

import os, httpx

headers = {'Idempotency-Key': 'unique-request-key', 'Content-Type': 'application/json'}
headers["Authorization"] = "Bearer " + os.environ["SECURITY_RUN_API_KEY"]
response = httpx.request('POST', os.environ["SECURITY_RUN_URL"].rstrip("/") + '/v1/tool-runs',
    headers=headers,
    json={'tool': 'yara', 'timeout_seconds': 30, 'invocation': {'executable': 'yara', 'args': ['-s', 'rules.yar', 'sample.txt'], 'files': [{'path': 'rules.yar', 'artifact_id': 'artifact_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'}, {'path': 'sample.txt', 'artifact_id': 'artifact_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'}]}})
response.raise_for_status()
print(response.text)

Request

const base = process.env.SECURITY_RUN_URL.replace(/\/$/, "");
const headers = {
  "Idempotency-Key": "unique-request-key",
  "Content-Type": "application/json"
};
headers.Authorization = `Bearer ${process.env.SECURITY_RUN_API_KEY}`;
const response = await fetch(base + "/v1/tool-runs", {
  method: "POST",
  headers,
  body: JSON.stringify({
  "tool": "yara",
  "timeout_seconds": 30,
  "invocation": {
    "executable": "yara",
    "args": [
      "-s",
      "rules.yar",
      "sample.txt"
    ],
    "files": [
      {
        "path": "rules.yar",
        "artifact_id": "artifact_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      {
        "path": "sample.txt",
        "artifact_id": "artifact_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
      }
    ]
  }
})
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.text());