Launch a background analysis job (operator+).

POST

/api/v1/analysis/jobs

curl --request POST \
  --url https://example.com/api/v1/analysis/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "baseline_secs": 1, "depth": "example", "family": "example", "notify": true, "scope_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope_kind": "example", "scope_label": "example", "sensitivity": 1, "tool": "example", "window_secs": 1 }'

Authorizations

• bearer

Request Body^required

Media typeapplication/json

Request body to launch an analysis (launch drawer / report config bar).

object

baseline_secs

integer | null format: int64

depth

string | null

family

string | null

notify

boolean | null

scope_id

string | null format: uuid

scope_kind

required

string

scope_label

required

string

sensitivity

number | null format: double

tool

required

string

window_secs

required

integer format: int64

Example^generated

{
  "baseline_secs": 1,
  "depth": "example",
  "family": "example",
  "notify": true,
  "scope_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "scope_kind": "example",
  "scope_label": "example",
  "sensitivity": 1,
  "tool": "example",
  "window_secs": 1
}

Responses

200

The queued job row; it progresses over /api/v1/stream/analysis

Media typeapplication/json

A job row, as served to the API / SSE. Timestamps are epoch-millis so the WebUI formats relative times without a date dependency.

object

created_ms

required

integer format: int64

error

string | null

finding_count

required

integer format: int32

finished_ms

integer | null format: int64

id

required

string format: uuid

params

required

pct

required

integer format: int32

phase

string | null

scope_id

string | null format: uuid

scope_kind

required

string

scope_label

required

string

started_ms

integer | null format: int64

state

required

Where an analysis run is in its lifecycle.

A bare String until v0.2.6, and the cost of that was paid twice. The vocabulary had to be written out by hand at the API edge to validate the runs filter, and again in the WebUI to fill its dropdown — two lists nothing compared. Worse, state: string compares equal to any string: the in-app “your analysis finished” notice tested state === 'succeeded', which is the report-run vocabulary, so every successful analysis announced itself as a failure. Typing it makes that comparison a compile error on both sides.

string

Allowed values: queued running done failed cancelled unknown

summary

string | null

tool

required

string

Example

{
  "state": "queued"
}

400

Unknown tool, unknown scope kind, or a group/node scope with no scope_id

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"
  }
}

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 below Operator

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"
  }
}

429

The runner is at its concurrency or rate limit — retryable

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

This deployment has no runner

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"
  }
}