# Submit a tool run



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



`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 →](https://www.security.run/docs/quickstart.html)



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



### Parameters



#### `authorization` · `header · string | null` · required



#### `idempotency-key` · `header · string | null` · required



### Request body



#### `tool` · `string`



Tool



Default: "yara"



#### `operation` · `string | null`



Operation



#### `version` · `string | null`



Version



#### `inputs` · `YaraInputs | null`











##### `artifact_id` · `string` · required



Artifact Id



Pattern: "^artifact\_\[a-f0-9\]{32}$"



##### `rules_artifact_id` · `string | null`



Rules Artifact Id



#### `invocation` · `NativeInvocation | null`











##### `executable` · `string | null`



Executable



##### `args` · `array of string`



Args



Max items: 256



##### `files` · `array of NativeFile`



Files



Max items: 64



###### `path` · `string` · required



Path



###### `artifact_id` · `string` · required



Artifact Id



Pattern: "^artifact\_\[a-f0-9\]{32}$"



###### `executable` · `boolean`



Executable



Default: false



##### `empty_files` · `array of string`



Empty Files



Max items: 64



##### `directories` · `array of string`



Directories



Max items: 64



##### `stdin_artifact_id` · `string | null`



Stdin Artifact Id



##### `environment` · `object`



Environment



##### `working_directory` · `string`



Working Directory



Default: "."



##### `outputs` · `array of string`



Outputs



Max items: 64



##### `success_exit_codes` · `array of integer`



Success Exit Codes



Max items: 16



#### `timeout_seconds` · `integer`



Timeout Seconds



Default: 30 · Minimum: 1.0 · Maximum: 120.0



#### `target_profile` · `string | null`



Target Profile



### Responses



- `202` Successful Response

- `422` Validation Error

## Request

```bash
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

```python
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

```javascript
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());
```