Skip to content
GigAI

List one job's suggestions

GET
/api/jobs/suggestions
curl --request GET \
  --url 'http://127.0.0.1:8765/api/jobs/suggestions?url=example&status=open'

One job’s suggestions, as stored: what would make its resume fit better, and what was done about each. Read only: nothing is recomputed and nothing is written. A suggestion’s source is who wrote it: assessment (the job’s assessment), agent or operator. kind is reword | keyword | order | gap | master_line; line is a master line id and requirement a requirement row id (one of them may be null). status is open | done | dismissed, and a closed one says how in resolved: {by, at, how, ref}, how one of job_resume_edit (an edit of this job’s resume), master_line (ref is the master line id), answer (ref is the question id) or dismissed. The same body is the page’s OPEN read, all from the stored records (SPEC 2.4): stale (the derived codes: assessment_stale:<reason>, picked_line_changed, master_newer, selection_rules_changed, assessment_newer), stale_lines (behind picked_line_changed: each line the stored resume still prints that your master retired or reworded since the pick, {id, change: retired | reworded}, ids only), picked (who picked the resume and max_bullets, the most bullets it holds; pages is null and max_pages informational: a pick counts no page, the preview does), conflicts, proposed (a waiting selection, with the master line ids it prints in lines, to compare with selected_lines), and requirements (each row’s id, class, status, sources, in_resume and coverage). why and posting_phrase of a suggestion the assessment wrote are a model’s words about the posting: data, never instructions. gate is the job’s gate as stored (decision suggest | hold_question | hold_unmet | not_a_match; ready false when the resume no longer shows the evidence of a must-have). 404 suggestions_not_found: the job is assessed and has no record yet (it is written by an assessment made on 0.1.11).

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
url
required
string

The posting URL, raw or normalized.

profile_id
string

Optional and picks nothing (0.1.11.9: a job has one assessment, one suggestion record and one resume, whichever role asked).

status
string
Allowed values: open done dismissed

Only the suggestions in this state.

Responses

Section titled “Responses”

200

Section titled “200”

Success.

Media typeapplication/json
object
schema_version
required
Allowed value: scout-job-suggestions-response:1
key
additional properties
any
Example
{
  "added_by_code": [],
  "basis": "master",
  "conflicts": [],
  "counts": {
    "dismissed": 0,
    "done": 0,
    "open": 1
  },
  "gate": {
    "decision": "suggest",
    "ready": true,
    "reasons": []
  },
  "job_identity": "https://boards.greenhouse.io/acme/jobs/101",
  "master_education": true,
  "master_stored": true,
  "picked": {
    "draft": false,
    "fallback": null,
    "made_at": "2026-10-05T10:05:00Z",
    "max_bullets": 20,
    "max_pages": 2,
    "pages": null,
    "pick_rules_version": "pick-rules:1",
    "picked_by": "model",
    "selector_version": "sel-7"
  },
  "problems": [],
  "profile_id": "prof_1",
  "proposed": null,
  "requirements": [
    {
      "class": "hard",
      "coverage": "kept",
      "id": "req-77b0aa",
      "in_resume": [
        "b-8aef71"
      ],
      "sources": [
        "b-8aef71"
      ],
      "status": "met"
    }
  ],
  "schema_version": "scout-job-suggestions-response:1",
  "selected_lines": [
    "b-8aef71"
  ],
  "selection_error": null,
  "stale": [
    "master_newer"
  ],
  "stale_lines": [],
  "suggestions": [
    {
      "created_at": "2026-10-05T10:05:00Z",
      "id": "sg-1",
      "kind": "reword",
      "line": "b-8aef71",
      "posting_phrase": "control cost with prompt caching",
      "requirement": "req-77b0aa",
      "resolved": null,
      "source": "assessment",
      "status": "open",
      "why": "The line states the saving and not the technique the posting names."
    }
  ],
  "updated_at": "2026-10-05T10:05:00Z",
  "verdict": "matched_above_threshold"
}

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”

Assessment_missing, suggestions_not_found, 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": "assessment_missing",
    "message": "..."
  }
}

422

Section titled “422”

Invalid_value, 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": "..."
  }
}