---
title: "# Create Simulation"
method: POST
path: "/v1/apv/simulations"
tags: ["Apv"]
---

# # Create Simulation

`POST /v1/apv/simulations`

## Request

- Base URL: `https://api.picussecurity.com`
- URL: `https://api.picussecurity.com/v1/apv/simulations`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/picussecurity/apis/picus-rest-api/docs/v1/apv/simulations/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a Gray-Box, Red-Team, or Black-Box simulation. GRAY_BOX/BLACK_BOX are agent-based
(agent_id required; initial_machine additionally required for GRAY_BOX) and can be launched
instantly or on a schedule. RED_TEAM is stager-based (stager_id required instead of agent_id)
and only launches instantly - initial_machine and schedule are both rejected if sent.

## Request body

- CreateSimulationBody
  - `agent_id` integer: Required for GRAY_BOX/BLACK_BOX (agent-based). Not supported for RED_TEAM - the request is rejected if this is non-zero (use stager_id instead).
  - `description` string
  - `initial_machine` CreateSimulationInitialMachine
    - `domain_controller_ip` string
    - `hostname` string
    - `password` string
    - `user_domain` string
    - `username` string
  - `name` string
  - `policy` CreateSimulationPolicy: initial machine and agent/stager. inclusion/exclusion are CIDR/IP/hostname strings. BLACK_BOX only has an inclusion scope: inclusion is required and exclusion is rejected if sent.
    - `assessment_duration` integer: How long the assessment is allowed to run, in minutes. Optional; defaults to 7 days when omitted. Validated (30-14400) only when provided.
    - `domain_name` string: Ignored for GRAY_BOX (initial_machine.user_domain already carries its domain context). Optional for BLACK_BOX - used as the domain scope if provided.
    - `enable_brute_force` boolean: GRAY_BOX/BLACK_BOX only; ignored for RED_TEAM. When true, the simulated attacker also attempts credential brute-forcing (SSH/Telnet/VNC/FTP) with the default configuration.
    - `enable_opc` boolean
    - `exclusion` string[]: Not supported for BLACK_BOX - the request is rejected if this is non-empty.
    - `inclusion` string[]: Required for BLACK_BOX.
  - `schedule` CreateSimulationSchedule: CreateSimulationSchedule: omit the whole "schedule" object to launch instantly instead. For WEEKLY/MONTHLY, the day of the week/month is derived from start_time - there's no separate field for it.
    - `frequency` string
    - `frequency_interval` integer: Ignored for ONCE (always sent as 0 downstream). Optional otherwise - defaults to 1. Valid range: 1-3 for WEEKLY/MONTHLY, 1-6 for DAILY.
    - `start_time` integer: Epoch milliseconds of the first run, matching every time field this API returns. Must be in the future and at most 365 days ahead - this example value is illustrative only, not a valid literal input.
  - `simulation_type` string
  - `stager_id` string: Required for RED_TEAM (use this instead of agent_id) - which stager to generate. Ignored for agent-based simulations (GRAY_BOX/BLACK_BOX).

## Response `201`

CreateSimulationResponseSwagger

- ApvCreateSimulationOutput
  - `run_uuid` string
  - `simulation_uuid` string

## Other responses

- `401`: unauthorizedErrorSwagger is represents unauthorized error
- `422`: validationErrorSwagger is represents the erroneous cases
- `default`: genericErrorSwagger is represents the erroneous cases

## Changes

- **2026-10-13** `da387004d99b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/picussecurity/apis/picus-rest-api/changes/v1/apv/simulations/post.md)

---

[API](https://skmtc.dev/picussecurity/apis/picus-rest-api.md) - [All operations](https://skmtc.dev/picussecurity/apis/picus-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/picussecurity/apis/picus-rest-api/revisions/da387004d99b?raw)