Skip to content
GigAI

Change the background settings

PUT
/api/settings/background
curl --request PUT \
  --url http://127.0.0.1:8765/api/settings/background \
  --header 'Content-Type: application/json' \
  --data '{ "sources": { "auto_refresh": false } }'

Change background settings. Send only the keys to change; at least one. Every other key of the project’s settings.json is kept, and the file is replaced in one step. The refresh thread reads the file at every look and is woken by this call, so turning sources.auto_refresh off stops the background checks and the model tagging at once (an update already running finishes), and new sources.check_times decide the next check. A list of check times is stored sorted, without repeats; an empty list, more than 12 times or anything that is not HH:MM (00:00 to 23:59) is 422 invalid_value. 409 settings_unreadable: the stored file is not one Scout can read; it is left as it is. The answer is the GET body after the change. settings is what the project’s settings file says (a key it does not hold shows its default): the values a form edits. effective is what the background jobs act on now, each block with the source that decided it: default, setting, environment (an environment variable overrides the file) or settings_unreadable. readable is false when the file exists and cannot be read: every background job is then off. sources.auto_refresh off stops all background work, the model tagging included; sources.check_times is when the background checks run: weekdays and weekends, each 1 to 12 24-hour HH:MM times in the machine’s local time (in effective with its own source, and default: the times a reset puts back); tagging.model_enabled lets a model tag titles the rules cannot place, tagging.backfill_enabled also tags titles no active profile can reach, with tagging.tag_backfill_model; snapshot.enabled allows the metadata snapshot download from snapshot.manifest_url. pipeline is the background pipeline (tailor, assess again, Scout ATS score, Scout label, for jobs the user engaged with): enabled, auto_jobs_per_trigger (one trigger queues at most this many jobs; the rest wait for an approval), max_model_calls_per_day (for the whole install, every profile together), label_min_ats (the Scout ATS score a job needs for the Scout label recommended; 0 to 100) and models (the model target of the tailor and reassess steps; a step left out runs with the project’s model target). rank is the background rank, switched SEPARATELY from the pipeline (0.1.11.2): enabled (on by default; it ranks with pipeline.enabled off, and only postings that went up in the last 7 days, or that Scout first stored in them when a posting has no date) and its daily cap, max_calls_per_day and warn_calls_per_day. effective.pipeline holds all of them with their source (effective.pipeline.rank has its own enabled and source); with settings that cannot be read the pipeline and the rank are off (enabled false, source settings_unreadable): they never guess. The environment variable that turns the pipeline off turns the rank off too, unless the file names rank.enabled itself.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
pipeline

{enabled: boolean, auto_jobs_per_trigger: 0 to 1000, max_model_calls_per_day: 0 to 1000, label_min_ats: 0 to 100, models: {tailor, reassess: codex_cli|claude_cli|ollama_local|openrouter_api}}. null for a number puts its default back; null for a step, or for models, puts the project’s model target back.

object
rank

{enabled: boolean (the background rank’s own switch, separate from pipeline.enabled; on by default), max_calls_per_day: 0 to 1000, warn_calls_per_day: 0 to 1000, not above max_calls_per_day}. null puts the default back.

object
snapshot

{enabled: boolean, manifest_url: an http(s) URL, or null for the default location}.

object
sources

{auto_refresh: boolean, check_times: {weekdays: [HH:MM, …], weekends: [HH:MM, …]}}: the background checks of the sources and the local times they run at. A day left out keeps its times; null for a day, or for check_times, puts the default times back.

object
tagging

{model_enabled: boolean, backfill_enabled: boolean, tag_backfill_model: configured|haiku|openai}.

object
Example
{
  "sources": {
    "auto_refresh": false
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

Success.

Media typeapplication/json
object
schema_version
required
Allowed value: scout-background-settings:1
key
additional properties
any
Example
{
  "effective": {
    "pipeline": {
      "auto_jobs_per_trigger": 10,
      "enabled": true,
      "label_min_ats": 0,
      "max_model_calls_per_day": 40,
      "models": {},
      "rank": {
        "enabled": true,
        "max_calls_per_day": 100,
        "source": "default",
        "warn_calls_per_day": 60
      },
      "source": "default"
    },
    "snapshot": {
      "enabled": true,
      "manifest_url": "https://github.com/karthik446/gigai/releases/download/scout-snapshot/manifest.json",
      "source": "default"
    },
    "sources": {
      "auto_refresh": true,
      "check_times": {
        "default": {
          "weekdays": [
            "03:00",
            "07:00",
            "09:00",
            "11:00",
            "13:00",
            "15:00",
            "17:00",
            "19:00"
          ],
          "weekends": [
            "09:00",
            "18:00"
          ]
        },
        "source": "default",
        "weekdays": [
          "03:00",
          "07:00",
          "09:00",
          "11:00",
          "13:00",
          "15:00",
          "17:00",
          "19:00"
        ],
        "weekends": [
          "09:00",
          "18:00"
        ]
      },
      "source": "default"
    },
    "tagging": {
      "backfill_enabled": false,
      "model_enabled": true,
      "source": "default",
      "tag_backfill_model": "configured"
    }
  },
  "readable": true,
  "schema_version": "scout-background-settings:1",
  "settings": {
    "pipeline": {
      "auto_jobs_per_trigger": 10,
      "enabled": true,
      "label_min_ats": 0,
      "max_model_calls_per_day": 40,
      "models": {}
    },
    "rank": {
      "enabled": true,
      "max_calls_per_day": 100,
      "warn_calls_per_day": 60
    },
    "snapshot": {
      "enabled": true,
      "manifest_url": "https://github.com/karthik446/gigai/releases/download/scout-snapshot/manifest.json"
    },
    "sources": {
      "auto_refresh": true,
      "check_times": {
        "weekdays": [
          "03:00",
          "07:00",
          "09:00",
          "11:00",
          "13:00",
          "15:00",
          "17:00",
          "19:00"
        ],
        "weekends": [
          "09:00",
          "18:00"
        ]
      }
    },
    "tagging": {
      "backfill_enabled": false,
      "model_enabled": true,
      "tag_backfill_model": "configured"
    }
  }
}

403

Section titled “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
Examplegenerated
{
  "error": {
    "allowed_keys": [
      "example"
    ],
    "code": "example",
    "message": "example"
  }
}

404

Section titled “404”

Target_unavailable

Media typeapplication/json
object
error
required
object
allowed_keys
Array<string>
code
required
string
message
required
string
key
additional properties
any
Example
{
  "error": {
    "code": "target_unavailable",
    "message": "..."
  }
}

409

Section titled “409”

Settings_unreadable

Media typeapplication/json
object
error
required
object
allowed_keys
Array<string>
code
required
string
message
required
string
key
additional properties
any
Example
{
  "error": {
    "code": "settings_unreadable",
    "message": "..."
  }
}

415

Section titled “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
Examplegenerated
{
  "error": {
    "allowed_keys": [
      "example"
    ],
    "code": "example",
    "message": "example"
  }
}

422

Section titled “422”

Wrong_type, unknown_key, invalid_value, bad_enum

Media typeapplication/json
object
error
required
object
allowed_keys
Array<string>
code
required
string
message
required
string
key
additional properties
any
Example
{
  "error": {
    "code": "wrong_type",
    "message": "..."
  }
}