Skip to content
GigAI

Add, resolve or dismiss a suggestion of one job

POST
/api/jobs/suggestions
curl --request POST \
  --url http://127.0.0.1:8765/api/jobs/suggestions \
  --header 'Content-Type: application/json' \
  --data '{ "action": "resolve", "actor": "agent", "how": "job_resume_edit", "job_url": "https://boards.greenhouse.io/acme/jobs/101", "suggestion_id": "sg-1" }'

Add a suggestion to one job, set one to done, or dismiss one. No model call. add writes one more open suggestion with source the writer (operator or agent); its line must be a line of the master (422 unknown_line) and its requirement a row of this job (422 unknown_requirement); a why or posting_phrase that holds a contact detail is 422 personal_info_refused. resolve sets one to done and records {by, at, how, ref}; dismiss sets one to dismissed. A closed suggestion stays in the record and its id is never used again. A key of another action is 422 invalid_value. The answer is the job’s suggestions after the change, with added, resolved or dismissed: the id it was about. A hand-back that settles suggestions names them itself (gigai scout resume store --resolves sg-1,sg-3).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
action
required

What to do.

string
Allowed values: add resolve dismiss
actor

Who writes: recorded as written_by. Also the X-GigAI-Actor header. Without either, a write from the Scout UI (a browser page of this server) is the operator’s and any other loopback write is the agent’s.

string
Allowed values: operator agent
how

Resolve: what settled it.

string
Allowed values: job_resume_edit master_line answer
job_url
required

The posting’s link: the ONE job.

string
kind

Add: what the suggestion is about.

string
Allowed values: reword keyword order gap master_line
line

Add: the master line it is about, by id. line, requirement or both.

string
posting_phrase

Add: at most 60 characters of the posting the suggestion points at.

string
profile_id

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

string
ref

Resolve: what it points at: the master line id (master_line) or the question id (answer).

string
requirement

Add: the requirement row it is about, by id (req-…).

string
suggestion_id

Resolve, dismiss: the suggestion, by id (sg-<n>).

string
why

Add: what would help, 1 to 300 characters. No name and no contact detail.

string
Example
{
  "action": "resolve",
  "actor": "agent",
  "how": "job_resume_edit",
  "job_url": "https://boards.greenhouse.io/acme/jobs/101",
  "suggestion_id": "sg-1"
}

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
{
  "counts": {
    "dismissed": 0,
    "done": 1,
    "open": 0
  },
  "gate": {
    "decision": "suggest",
    "ready": true,
    "reasons": []
  },
  "job_identity": "https://boards.greenhouse.io/acme/jobs/101",
  "profile_id": "prof_1",
  "resolved": "sg-1",
  "schema_version": "scout-job-suggestions-response:1",
  "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": {
        "at": "2026-10-05T10:06:00Z",
        "by": "agent",
        "how": "job_resume_edit",
        "ref": null
      },
      "source": "assessment",
      "status": "done",
      "why": "The line states the saving and not the technique the posting names."
    }
  ],
  "updated_at": "2026-10-05T10:06:00Z"
}

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

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”

Unknown_key, wrong_type, invalid_value, bad_enum, personal_info_refused, unknown_line, unknown_requirement

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