Campaigns

Saved campaigns: which attacks to run against an agent, on which goals, judged how. Includes the technique catalogue, the campaign spec schema, the launch preflight and the launch itself, which queues a run.

📄️List campaigns

Returns the organization's saved campaigns, ordered by name, 10 per page (`page`): those saved from the dashboard or this API (`origin: dashboard`) and by `hackagent campaign run FILE` (`origin: cli`). Accepts an API key or a login token.

📄️Create a campaign

Saves a campaign in the caller's organization: an agent and a spec of the attacks to run against it. The target comes from the agent and the execution settings from the server, so the spec has no `target` or `execution`. The spec is validated as the SDK would (techniques, their parameters and roles, judges, dataset), and credentials must be `${VARIABLE}` references to organization secrets. Nothing runs until the campaign is launched (`POST /campaign/{id}/launch`). 403 when the caller has no organization.

📄️Retrieve a campaign

Returns one saved campaign of the caller's organization.

📄️Replace a campaign

Replaces a campaign's `name`, `description`, `agent` and `spec` (send them all), validated as on creation. Runs already launched keep the spec they were launched with.

📄️Update a campaign

Changes only the fields sent of a campaign, validated as on creation.

📄️Delete a campaign

Deletes a saved campaign. Its runs are kept, with `campaign` set to null.

📄️Launch a campaign

Queues a run of the saved campaign: a campaign run in status `PENDING`, whose `run_config` holds the spec resolved with the agent as target. With `executor: cloud`, HackAgent's cloud worker claims and executes it, and its LLM gateway calls are charged to the organization's credits. With `executor: local`, the response's `command` (`hackagent run <id>`) executes it on your machine. The launch runs the preflight checks first (see `GET /campaign/{id}/preflight`) and queues nothing when one fails (400 with `problems`). Follow the run with `GET /run/{id}/summary`.

📄️Preflight a campaign launch

Runs the checks a launch with the same `executor` would run, without queueing anything: `ok` is false and `problems` says why when the launch would be refused. Both executors need a caller of the campaign's organization (`ACCOUNT_INVALID`) and an agent type the executor can run (`AGENT_TYPE_NOT_SUPPORTED`). The cloud also needs a cloud worker on this installation (`CLOUD_UNAVAILABLE`), the minimum credit balance (`INSUFFICIENT_CREDITS`), an agent and spec it can reach and load (`AGENT_NOT_CLOUD_RUNNABLE`, `AGENT_NEEDS_CONFIGURATION`, `SPEC_NOT_CLOUD_RUNNABLE`), every secret the spec references (`MISSING_SECRETS`), and a free slot under the organization's limit of concurrent cloud runs (`CLOUD_CONCURRENCY_LIMIT`).

📄️Save and launch a campaign

Creates a campaign from the body (as `POST /campaign`) and launches it with `executor` (as `POST /campaign/{id}/launch`) in one call. The campaign is saved only when the launch passes its checks; the run's `campaign` is its id.

📄️Get the campaign spec schema

The JSON Schema campaign specs are validated against (for the SDK version this API runs), and the built-in goal datasets a spec can name as `dataset.source` with `type: preset`.

📄️Start a CLI campaign run

Used by `hackagent campaign run FILE`. Saves the file's campaign, by name among the organization's CLI campaigns (a dashboard campaign of the same name is left alone), and creates its campaign run already claimed by the caller: status `RUNNING`, executor `cli`. The caller then executes it like any executor, with heartbeats, child runs, results and a final `finish`. The agent must belong to the caller's organization.

📄️List attack techniques

The catalogue of attack techniques of the SDK version this API runs: for each, its category, its parameters (as form fields and as JSON Schema) and the model roles it requires or accepts. Use it to write the `attacks` of a campaign spec. Not paginated.