SoftSolzSoftSolz
HomeAPI GuideAPI ReferenceWidget Tester

Write the explanation for one finding

Overwrites any narrative on file and marks it as written by your app. 404 finding_not_found means the id is not in this report.

PUThttps://app.softsolz.uk/api/v1/services/seo/runs/{run_id}/findings/{finding_id}/narrative

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Path Params

run_idstringrequired
finding_idstringrequired

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

narrativestringrequired

Two to four plain-English sentences that explain the finding from its evidence_json numbers: what moved, by how much, and the likely reason. No guesses beyond the numbers. At most 2000 characters.

confidencenumber

0 to 1, how sure you are of the explanation.

Response

Response Body

idstringFinding id. Use it as finding_id when writing a narrative or a recommendation.
run_idstringReport the finding belongs to.
detectorstringWhich detector fired: page_movement, query_movement, content_decay, cannibalisation, topic_cannibalisation, striking_distance, ctr_gap, lost_queries, buried_opportunity, rising_topic, intent_mismatch, broken_internal_link, lost_backlink, broken_backlink_target or internal_link_opportunity.
severitystringHow serious it is.
entity_typestringsite, page, query, query_page, link or topic.
impact_scorenumberRanking score used to order findings, higher first.
metric_deltanumber | nullChange in the headline metric between the two months.
page_pathstring | nullPage path when the finding is about a page.
page_urlstring | nullFull page URL when the finding is about a page.
query_textstring | nullSearch query when the finding is about a keyword.
evidence_jsonobjectThe numbers behind the finding: current, prior and delta metric points plus detector-specific extras. Write narratives from these, never from guesses.
narrativestring | nullPlain-English explanation of the finding. Null until someone writes one.
narrative_confidencenumber | null0 to 1 confidence attached to the narrative.
narrative_sourcestring | nullsoftsolz when SoftSolz wrote it, api when a connected app did.
narrative_authorstring | nullName of the app or key that wrote the narrative.
created_atstringWhen the finding was detected.

Request

curl --request PUT \
--url https://app.softsolz.uk/api/v1/services/seo/runs/{run_id}/findings/{finding_id}/narrative \
--header 'Authorization: Bearer sk_live_your_key' \
--header 'Content-Type: application/json' \
--data '{
"narrative": "Clicks fell from 120 to 80 because the page slipped from position 8.9 to 11.2, off page one.",
"confidence": 0.8
}'

Credentials

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 200

{
"data": {
"id": "3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23",
"run_id": "3f2b9c44-8f4e-4d0a-9c1b-2a7d6e5f1a23",
"detector": "striking_distance",
"severity": "info",
"entity_type": "query",
"impact_score": 42.5,
"metric_delta": -35,
"page_path": "/blog/sourdough-guide",
"page_url": null,
"query_text": "sourdough starter",
"evidence_json": {
"current": {
"clicks": 80,
"position": 11.2
},
"prior": {
"clicks": 120,
"position": 8.9
}
},
"narrative": "Clicks fell by a third because the page slipped from page one to page two.",
"narrative_confidence": 0.8,
"narrative_source": "api",
"narrative_author": "Claude",
"created_at": "2026-09-01T09:00:00.000Z"
}
}