Skip to content
GigAI

Edit a story

PUT
/api/stories/{story_id}
curl --request PUT \
  --url http://127.0.0.1:8765/api/stories/example \
  --header 'Content-Type: application/json' \
  --data '{ "actor": "agent", "period": "2022-2023", "revision": 1, "tags": [ "ci", "delivery", "kubernetes" ] }'

Edit a story: only the given fields change. At least one field. A given field replaces the stored one whole (narrative, tags, answers_questions and sources are not merged). Every write bumps revision and updated_at and records written_by. 409 revision_conflict carries the current story in the error. 0.1.10.7: the write also queues the background pipeline (tailored resume, assessment against it, Scout ATS score, Scout label) for every job of an active profile whose stored assessment left open a question this answers; at most pipeline.auto_jobs_per_trigger (10) jobs run, the rest wait for an approval (GET /api/pipeline/approvals). The pipeline’s tailoring replaces only a tailored resume the pipeline itself made: one tailored on demand (POST /api/tailored-resumes) or with a line chosen or edited (PUT /api/tailored-resumes/lines) is kept as it is, its updated_at unchanged, and the assessment, the Scout ATS score and the Scout label are made against it. Read what was queued with GET /api/pipeline.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
story_id
required
string

A story’s id (e.g. story:60_acme_ci_cut_time). Percent-encode it in the path.

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
answers_questions

The interview questions this story answers (at most 12).

array
company

Where it happened.

string
narrative

{situation, task, action, result}: loosely STAR, every part an optional string.

object
period

When; rough is fine.

string
raw

The user’s own words, kept as said (at most 16000 characters).

string
revision
required

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

integer
role

The role held.

string
sources

[{question_id, job_identity}]: the job question that triggered the story.

array
tags

Tags (lowercase, at most 12).

array
title

The title.

string
Example
{
  "actor": "agent",
  "period": "2022-2023",
  "revision": 1,
  "tags": [
    "ci",
    "delivery",
    "kubernetes"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Success.

Media typeapplication/json
object
schema_version
required
Allowed value: scout-stories-response:1
key
additional properties
any
Example
{
  "schema_version": "scout-stories-response:1",
  "story": {
    "answers_questions": [
      "Tell me about a time you improved a slow process"
    ],
    "company": "Acme",
    "created_at": "2026-10-02T15:00:00.000000Z",
    "history": [
      {
        "action": "added",
        "at": "2026-10-02T15:00:00.000000Z",
        "by": "agent"
      }
    ],
    "jobs": [],
    "narrative": {
      "action": "Moved the runners to Kubernetes and cached the image layers.",
      "result": "Build time fell 60 percent.",
      "situation": "Builds took forty minutes and blocked every merge.",
      "task": "Make the pipeline fast enough to merge several times a day."
    },
    "period": "2023",
    "raw": "Our builds took forty minutes, so I moved the runners to Kubernetes and cached the layers. It came down to sixteen.",
    "revision": 1,
    "role": "Staff Engineer",
    "sources": [
      {
        "job_identity": "https://boards.greenhouse.io/acme/jobs/101",
        "question_id": "tooling:kubernetes"
      }
    ],
    "story_id": "story:60_acme_ci_cut_time",
    "tags": [
      "ci",
      "delivery"
    ],
    "title": "Cut CI time 60% at Acme",
    "updated_at": "2026-10-02T15:00:00.000000Z",
    "written_by": "agent"
  }
}

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”

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

409

Section titled “409”

Revision_conflict

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

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