---
title: "Query Story"
method: POST
path: "/api/mcp/query_story"
tags: ["mcp"]
---

# Query Story

`POST /api/mcp/query_story`

## Request

- Base URL: `https://writer.swapp1990.org` (the document declares no server; this is the origin it was published from)
- URL: `https://writer.swapp1990.org/api/mcp/query_story`
- Auth: none declared

Semantic search over a story's text (whole story, latest revision).

Returns `{job_id, question, passages}` where each passage is
`{chapter, para, text, score}` — the most relevant excerpts for the
question, with citations. Use to pull a specific fact, check continuity,
or find where something happened. Pass `chapter` to scope to one chapter.
`score` is the final hybrid relevance score; `semantic_score` is the
raw embedding similarity before lexical/phrase reranking. Lexical
fallback expands common rewrite-check concepts, so
`matched_query_expansions` may include synonym or morphology hits.
query_story is a locator, not proof. For rewrite claims, inspect `retrieval_mode`, `confidence`, and
`needs_read_story_verification`; use `read_story` on `recommended_read`
when confidence is not high or fallback retrieval was used.

## Request body

- QueryStoryInput
  - `job_id` string, required: The story job id.
  - `question` string, required: Natural-language question about the story's text.
  - `k` integer: How many passages to return.
  - `chapter` integer, nullable: Narrow the search to one chapter; omit for whole story.

## Response `200`

Successful Response

- QueryStoryResponse
  - `job_id` string, nullable
  - `answer` string, nullable
  - `citations` unknown[], nullable
    - unknown
  - `matches` unknown[], nullable
    - unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api.md) · [All operations](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/swapp1990/apis/writeforyou-mcp-api/revisions/ce5e2a89ab4d?raw)