Start a find-jobs run (deprecated)

Deprecated

POST

/api/run

curl --request POST \
  --url http://127.0.0.1:8765/api/run \
  --header 'Content-Type: application/json' \
  --data '{ "config_digest": "sha256:...", "keywords": [ "kubernetes" ], "schema_version": "scout-find-jobs-run-request:1", "selection_cap": 10 }'

Deprecated: start a find-jobs run (acquire, rank, assess up to the cap). Deprecated since 0.1.10.7 and kept for one release for scripts: a run is no longer the way in. Search with GET /api/postings (the stored index, live, no run), see what is new with GET /api/new, and assess on approval with POST /api/postings/assess or POST /api/new; ranking runs in the background. Existing runs stay readable (GET /api/runs and the routes under it) and what they assessed is in the read model (POST /api/runs/import). Reads the boards over the network and spends model calls on assessment; returns as soon as the run is allocated. Poll GET /api/runs/{run_id}. keywords filter the postings the profile’s titles matched, through the full-text index (title and description): a posting whose stored text matches none of them is dropped; one keyword is enough, each is matched as a phrase. A posting with no stored text cannot be checked: it is kept and counted. They never add postings the titles did not match. The run’s sealed config carries them (keywords), and GET /api/runs/{run_id}/progress boards.keywords reports {terms, mode: filter, applied, reason, message, matched, dropped, text_not_checked}; with no text index on this machine applied is false, reason is no_text_index, text_index_unavailable or bad_query, and the search runs as if no keyword was given. config_digest is the one GET /api/config returned (keywords are not part of it).

Request Body^required

Media typeapplication/json

object

config_digest

required

Config_digest from GET /api/config.

string

consent

required

The consent envelope the UI sends.

object

keywords

Optional full-text keywords for this one search: up to 20 phrases of at most 100 characters.

array

model_target

required

Model target.

string

schema_version

required

Scout-find-jobs-run-request:1.

string

selection_cap

required

Postings to assess (1..50).

integer

selection_rule

required

Which postings the cap keeps.

string

Example

{
  "config_digest": "sha256:...",
  "keywords": [
    "kubernetes"
  ],
  "schema_version": "scout-find-jobs-run-request:1",
  "selection_cap": 10
}

Responses

200

Success.

Media typeapplication/json

object

schema_version

required

Allowed value: scout-find-jobs-run-response:1

key

additional properties

any

Example

{
  "node_receipts": [],
  "run_id": "run_20260929T100000Z",
  "schema_version": "scout-find-jobs-run-response:1",
  "status": "running"
}

403

Forbidden / forbidden_origin: loopback peer and Host 127.0.0.1:<port> or localhost:<port> only (Origin too on writes).

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example^generated

{
  "error": {
    "allowed_keys": [
      "example"
    ],
    "code": "example",
    "message": "example"
  }
}

404

Config_missing

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example

{
  "error": {
    "code": "config_missing",
    "message": "..."
  }
}

409

Config_digest_mismatch

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example

{
  "error": {
    "code": "config_digest_mismatch",
    "message": "..."
  }
}

415

Unsupported_media_type: writes need Content-Type: application/json.

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example^generated

{
  "error": {
    "allowed_keys": [
      "example"
    ],
    "code": "example",
    "message": "example"
  }
}

422

Invalid_value, wrong_type, unknown_key

Media typeapplication/json

object

error

required

object

allowed_keys

Array<string>

code

required

string

message

required

string

key

additional properties

any

Example

{
  "error": {
    "code": "invalid_value",
    "message": "..."
  }
}