Ask the poller running a sweep to stop (ADR-068 Increment 2).

POST

/api/v1/discovery/scan/{id}/cancel

curl --request POST \
  --url https://example.com/api/v1/discovery/scan/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/cancel \
  --header 'Authorization: Bearer <token>'

ManageConfig, the same as starting one: stopping a sweep is the same authority as causing it.

Answers 200 for a scan this core has no record of, unlike analysis’s cancel. That asymmetry is deliberate. Scan state is in memory, so a restarted core forgets sweeps its pollers are still running, and requiring a local record would make exactly those sweeps — the ones an operator most wants to stop — unstoppable. The analysis endpoint 404s because there the 200/404 split answers “is that job running” for any id a caller cares to try; here the id is an unguessable UUID and the caller already holds ManageConfig, so the split would only reveal whether this process remembers something.

Authorizations

• bearer

Parameters

Path Parameters

id

required

string format: uuid

Scan id returned when the sweep was accepted

Responses

200

The stop was published. Not a promise that the sweep stopped — watch the scan’s state for that

Media typeapplication/json

The outcome of asking a sweep to stop.

⚠️ Deliberately does not claim the sweep stopped, and the field names carry that. Core broadcasts the stop and cannot know who — or whether anyone — acted on it, so the honest report is “requested, and here is whether the pollers that might be running it understand the command”. The confirmation arrives later, as the scan’s own state going to cancelled.

object

poller_supports_cancel

required

Whether every live poller that could be running this sweep advertises cancellation support.

⚠️ An approximation, which is why it is not called will_stop. A sweep on the global route could be held by any live poller, so this is the answer across all of them; even for a pool-scoped sweep it says the pool can stop sweeps, not that the poller holding this one will. false means at least one poller predates the feature and the sweep may run to completion.

boolean

pool

The pool the stop was published to; null for the global subject.

string | null

requested

required

The stop was published. Always true on a 200 — a publish failure is a 500.

boolean

Example^generated

{
  "poller_supports_cancel": true,
  "pool": "example",
  "requested": true
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks ManageConfig

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Skeleton mode has no write side, or this core is not the HA leader

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}