---
title: "Create a machine pentest"
method: POST
path: "/v1/pentests/"
tags: ["pentests"]
---

# Create a machine pentest

`POST /v1/pentests/`

## Request

- Base URL: `https://api.ethiack.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ethiack.com/v1/pentests/`
- Auth: none declared

Create a machine pentest, in draft.

Conflicts (HTTP 409) when the organization is already running as many
continuous pentests as its subscription meters. The pentest is left
in draft, as the pre-rename endpoint left it: ``POST
{slug}/start`` is what puts it to work.

Args:
    body (CreateMachinePentestRequest): Owning organization and the
        seeding options.
    db (AsyncSession): Request-scoped database session.
    context (ActiveContext): Resolved caller identity and scope.

Returns:
    SuccessResponse: The pre-rename create envelope, carrying the new
        pentest's **slug** as ``id`` — that is what the endpoint
        answered, and a client stores what it is given.

## Request body

- CreateMachinePentestRequest: Body for creating a machine (continuous) pentest. Field-for-field the legacy ``CreateMachineEvent``, including the two defaults: a create with an empty body seeds the pentest's scope from the organization's assets and launches a recon over it. Attributes: organization_id (int | None): Owning organization. Required for partners, who must already hold delegated access to it; omitted by an organization caller, whose own organization is used. add_assets (bool): Seed scope with the organization's existing assets — verified domains as wildcards (every domain, when its integrator partner vouches for it), the rest as plain in-scope entries. launch_recon (bool): Launch a recon once the pentest exists. It needs somewhere to look, so it adds those domains as wildcards even when ``add_assets`` is false. end_date (datetime.datetime | None): When the pentest should end. Defaults to the organization's subscription end and may not outlast it. name (str | None): Display name; generated from the slug when omitted.
  - `organization_id` integer, nullable: Organization that owns the pentest. Required for partners; organization callers may omit it.
  - `add_assets` boolean: Add the organization's existing assets to scope, including verified domains as wildcard assets (every domain, when the organization's integrator partner vouches for it).
  - `launch_recon` boolean: Launch a recon for the pentest. Adds those domains as wildcard assets if they are not already there.
  - `end_date` string, date-time, nullable: End date in ISO 8601 format, timezone-aware and in the future. Defaults to the organization's subscription end, which it may not exceed.
  - `name` string, nullable: Display name. Generated from the slug when omitted.

## Response `201`

Successful Response

- SuccessResponse: Standard response for successful write operations. Matches the ``SuccessResponse`` contract from api-3. Attributes: code (int): HTTP status code. description (str): Human-readable result description. id (int | str | None): Created/affected resource ID. success (bool): Always ``True`` for successful responses.
  - `code` integer, required
  - `description` string, required
  - `id` union
    - integer
    - string
  - `success` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ethiack/apis/ethiack-api.md) - [All operations](https://skmtc.dev/ethiack/apis/ethiack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ethiack/apis/ethiack-api/revisions/4eaba89bfebf?raw)