Skip to content
GigAI

List stories

GET
/api/stories
curl --request GET \
  --url http://127.0.0.1:8765/api/stories

Every story of the user, with tags, dates, writer and the jobs that used it. Stories belong to the user, not to a profile. Each story: story_id, title, company, role, period (rough is fine), raw (the user’s own words, kept as said), narrative ({situation, task, action, result}, loosely STAR, every part optional), tags, answers_questions (the interview questions it answers), sources ([{question_id, job_identity}]: the job question that triggered it), jobs (the postings whose assessment cited it: kind used), written_by (operator | agent), created_at, updated_at, revision (send it back on PUT and DELETE) and the last writes in history. An assessment searches the stories locally for each job and puts only the few that match the posting into its prompt as evidence. total counts the stories before q and tag narrow them.

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
q
string

Only stories whose text holds this.

tag
string

Only stories with this tag.

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",
  "stories": [
    {
      "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"
    }
  ],
  "tags": [
    "ci",
    "delivery"
  ],
  "total": 1
}

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

422

Section titled “422”

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