Skip to content
GigAI

Edit, retire or restore an entry of the master

PUT
/api/master/entries
curl --request PUT \
  --url http://127.0.0.1:8765/api/master/entries \
  --header 'Content-Type: application/json' \
  --data '{ "id": "r-hex", "revision": 3, "sublines": [ "Staff Software Engineer | Jun 2019 - Feb 2023" ] }'

Edit, retire or restore a role, a project or a school of the master, by id. The entry’s id and its lines stay on an edit. note is one line of at most 300 characters; one that holds a comment mark (<!--, -->) or a word that starts with id:, tags:, backed: or gigai-master: is 422 master_note_invalid, and one that looks like contact data is 422 personal_info_refused. A note edit is one revision; the line’s mark stays, so no resume is printed again and no assessment goes stale. use retire takes the entry out with its lines (retired lists them); use restore puts it back where it stood, with the lines it had that the master does not hold. One new revision of the master. Send the revision you read: when the master changed since, the reply is 409 revision_conflict with error.current (the revision it is at now): read it again, then send the change on top of that. A text that looks like contact data (email, phone, link, address, a name line) answers 422 personal_info_refused and nothing is written. These are the rules of gigai scout resume master add | edit | remove (one implementation), so a refusal carries that command’s code. The reply carries the whole master after the write, status (revised, or unchanged when it already said this) with written, the id the change was about, retired (what the write took out, each with the revision that still holds it), and profiles: what the write did to the profiles’ selections (synced: a profile that shows an edited or retired line had its resume printed again; offers: new lines are offered, never added by themselves). Every tailoring made from the master is out of date after a write and is made again when the pipeline next looks at its profile. file says where the revision went in the resumes folder (null when nothing was written): wrote is master.md, or the file beside it (master-2.md) when master.md holds changes the user has not imported, which GigAI never replaces. Local only: no model call.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
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
heading

With use edit: the heading.

string
id
required

The entry’s id.

string
note

With use edit: the note, one line of at most 300 characters that says when this is the one to use ("" removes it). Read by the assessment and the user’s agent; never printed in a resume.

string
revision
required

The revision of the master you read; when it changed since, the reply is 409.

integer
sublines

With use edit: the lines under the heading, whole.

array
use

Edit (the default) changes the heading and/or the lines under it; retire takes the entry and its lines out; restore puts a retired one back with its lines.

string
Allowed values: edit retire restore
Example
{
  "id": "r-hex",
  "revision": 3,
  "sublines": [
    "Staff Software Engineer | Jun 2019 - Feb 2023"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Success.

Media typeapplication/json
object
schema_version
required
Allowed value: scout-master:1
key
additional properties
any
Example
{
  "action": "edit",
  "changes": {
    "added": 0,
    "changed": 1,
    "removed": 0
  },
  "file": {
    "beside": null,
    "name": "master.md",
    "not_imported": false,
    "path": "~/Documents/GigAI/resumes/master.md",
    "revision": 3,
    "state": "current",
    "written": true,
    "wrote": "master.md"
  },
  "id": "r-hex",
  "ids": [
    "b-hex-03"
  ],
  "master": {
    "content_sha256": "sha256:...",
    "counts": {
      "by_kind": {
        "bullet": 1,
        "other": 0,
        "skills": 1,
        "summary": 1
      },
      "by_strength": {
        "backed": 0,
        "quantified": 1,
        "stated": 2
      },
      "entries": 1,
      "ids": 4,
      "items": 3,
      "skills": 3
    },
    "entries": [
      {
        "bullets": [
          "b-hex-03"
        ],
        "end": 2023,
        "heading": "Hexa Cloud",
        "id": "r-hex",
        "note": null,
        "ongoing": false,
        "order": 3,
        "section": "experience",
        "source": null,
        "start": 2019,
        "sublines": [
          "Staff Software Engineer | Jun 2019 - Jan 2023"
        ],
        "written_by": null
      }
    ],
    "format": 1,
    "items": [
      {
        "backed": [],
        "entry_id": "r-hex",
        "id": "b-hex-03",
        "kind": "bullet",
        "mark": "5d0c2a4b9e1f7a36",
        "note": "agentic roles: lead with this",
        "order": 4,
        "section": "experience",
        "source": "from the user's chat on 3 Oct",
        "strength": "quantified",
        "tags": [
          "delivery"
        ],
        "text": "Led the migration of 40 services to Helm charts released through ArgoCD.",
        "written_by": "agent"
      }
    ],
    "parent_revision": "revision_7c1d7b9a-0d58-4f0b-8f27-91f4f6f6a2c3",
    "record_id": "record_...",
    "revision": 3,
    "revision_id": "revision_0b6f2f0e-5a0e-4c58-9a57-2d1b6a0c1e11",
    "revisions": 3,
    "sections": [
      "summary",
      "experience",
      "skills"
    ],
    "updated_at": "2026-10-04T10:05:00.000000Z",
    "written_by": "operator"
  },
  "near_duplicates": [],
  "profiles": {
    "offers": [
      {
        "label": "Staff Engineer",
        "new_lines": [
          "b-4f0c1a"
        ],
        "offer": "1 new master line: refresh?",
        "profile_id": "prof_1"
      }
    ],
    "synced": []
  },
  "retired": [],
  "schema_version": "scout-master:1",
  "skills": {
    "added": [],
    "already_listed": [],
    "line": null,
    "removed": []
  },
  "status": "revised",
  "warnings": [],
  "written": true
}

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”

Master_not_found, target_unavailable, master_item_not_found

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

409

Section titled “409”

Revision_conflict, master_line_exists, master_empty

Media typeapplication/json
object
error
required
object
allowed_keys
Array<string>
code
required
string
message
required
string
key
additional properties
any
Example
{
  "error": {
    "code": "revision_conflict",
    "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, personal_info_refused, master_text_invalid, master_markdown_invalid, master_edit_empty, master_edit_invalid, master_note_invalid

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