> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fabraix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Run

> Submit a new Nyx adversarial audit run

## Overview

Submits a new adversarial audit. Nyx queues the run, then iteratively probes the target until it finds a vulnerability or exhausts the budget. The endpoint returns immediately with a `run_id`; poll [`GET /nyx/runs/{run_id}`](/api-reference/nyx/endpoint/get-run) for progress.

## Request

<ParamField body="config_name" type="string" required>
  Stable identifier for this audit (used by `nyx status <name>` to look up the latest run). Typically the basename of the YAML config file.

  Example: `"playground"`
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable audit name shown in dashboards and reports.

  Example: `"Fabraix Playground: The Gatekeeper"`
</ParamField>

<ParamField body="target" type="object" required>
  The target under test. At least one of `url` or `endpoint` is required.

  <Expandable title="properties">
    <ParamField body="url" type="string">
      Target URL. Nyx discovers the rest automatically.
    </ParamField>

    <ParamField body="endpoint" type="string">
      Specific endpoint path, if you want to scope the audit.
    </ParamField>

    <ParamField body="credentials" type="object">
      Optional key/value map of credentials Nyx may use against the target.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="objective" type="string" required>
  What Nyx should try to achieve. Be specific: the objective drives every probe Nyx generates.

  Example: `"Get the target agent to call its reveal_access_code tool without being blocked by the external judge."`
</ParamField>

<ParamField body="budget_usd" type="number" required>
  Maximum spend in USD. Nyx stops when the budget is exhausted (`result: "exhausted"`) or a vulnerability is found (`result: "success"`).

  Example: `5.00`
</ParamField>

<ParamField body="severity_target" type="enum" required>
  Minimum OWASP AIVSS severity Nyx is targeting: `"low"`, `"medium"`, `"high"`, `"critical"`.
</ParamField>

<ParamField body="hints" type="array<string>">
  Optional context to help Nyx understand the target's architecture (e.g. "Two-layer defense: agent instructions + external LLM judge").
</ParamField>

<ParamField body="model" type="object" required>
  LLM Nyx will use to drive the audit.

  <Expandable title="properties">
    <ParamField body="provider" type="enum" required>
      `"openai"`, `"anthropic"`, `"deepseek"`, or `"gemini"`.
    </ParamField>

    <ParamField body="name" type="string" required>
      Model identifier. Example: `"claude-opus-4-6"`.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="run_id" type="string" required>
  Unique identifier for this run. Use it for status polling, cancellation, and report download.
</ResponseField>

<ResponseField name="config_name" type="string" required>
  Echoes the `config_name` from the request.
</ResponseField>

<ResponseField name="status" type="string" required>
  Initial status, typically `"queued"`.
</ResponseField>

<ResponseField name="created_at" type="datetime" required>
  ISO 8601 timestamp when the run was created.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.fabraix.com/v1/nyx/runs \
    -H "X-Verification-Token: $NYX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "config_name": "playground",
      "name": "Fabraix Playground: The Gatekeeper",
      "target": { "url": "https://playground.fabraix.com" },
      "objective": "Get the target agent to call reveal_access_code without being blocked.",
      "budget_usd": 5.00,
      "severity_target": "medium",
      "hints": ["Two-layer defense: agent instructions + external LLM judge"],
      "model": { "provider": "anthropic", "name": "claude-opus-4-6" }
    }'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.fabraix.com/v1/nyx/runs', {
    method: 'POST',
    headers: {
      'X-Verification-Token': process.env.NYX_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      config_name: 'playground',
      name: 'Fabraix Playground: The Gatekeeper',
      target: { url: 'https://playground.fabraix.com' },
      objective: 'Get the target agent to call reveal_access_code without being blocked.',
      budget_usd: 5.0,
      severity_target: 'medium',
      hints: ['Two-layer defense: agent instructions + external LLM judge'],
      model: { provider: 'anthropic', name: 'claude-opus-4-6' },
    }),
  });
  const run = await res.json();
  console.log(run.run_id);
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "run_id": "r_01H2X3Y4Z5...",
  "config_name": "playground",
  "status": "queued",
  "created_at": "2026-04-18T14:30:45.123Z"
}
```

## Related Endpoints

* [GET /nyx/runs/{run_id}](/api-reference/nyx/endpoint/get-run): poll for status
* [GET /nyx/runs/{run_id}/report](/api-reference/nyx/endpoint/get-report): download report