---
title: "Launch a recon"
method: POST
path: "/v1/pentests/{pentest_slug}/recons/"
tags: ["pentests"]
---

# Launch a recon

`POST /v1/pentests/{pentest_slug}/recons/`

## 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/{pentest_slug}/recons/`
- Auth: none declared

Launch a reconnaissance job for a pentest.

The launch is attributed to the dedicated recon machine user, not to
the caller — the requester's identity is recorded in the audit trail,
not on the launch row.

201 means the recon has been **scheduled**, not that artiacker-manager
has accepted it: the row is claimed here and POSTed by the dispatch task
the claim triggers, so the response carries a ``PENDING`` launch whose
status is the thing to read afterwards. A cluster that later declines it
is recorded as ``ERROR`` on that launch, not returned here.

Every failure maps through the centralized handlers, so nothing is
caught here: an unknown or out-of-scope slug is 404, a Cerbos denial
403, no wildcard in scope 400, an already-running recon 409, and an
unreachable artiacker-manager — for the already-running check, the one
call still made inline — 500.

Args:
    pentest_slug (str): Public pentest identifier.
    db (AsyncSession): Request-scoped database session.
    context (ActiveContext): Resolved caller identity and scope.

Returns:
    SuccessResponse: The legacy create envelope carrying the launch id.

## Path parameters

- `pentest_slug` string, required

## 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)