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.
PUT
https://app.softsolz.uk/api/v1/services/seo/runs/{run_id}/findings/{finding_id}/narrativeRecent Requests
Kept only in this browserTimeStatusTook
Send a request with Try it to see it here.
Path Params
run_idstringrequiredfinding_idstringrequiredHeaders
AuthorizationstringrequiredBearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.
Idempotency-KeystringOptional idempotency key for safe retries.
Body Params
narrativestringrequiredTwo 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.
confidencenumber0 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" }}