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

TimeStatusUser Agent

Make a request to see history.

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

narrativestring

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, striking_distance, ctr_gap, lost_queries, buried_opportunity, broken_internal_link, lost_backlink, broken_backlink_target or internal_link_opportunity.

severitystringHow serious it is.

entity_typestringsite, page, query or query_page.

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

import { SoftSolz } from '@softsolz/sdk';

const client = new SoftSolz({ apiKey: process.env.SOFTSOLZ_API_KEY });

const result = await client.seo.updateRunFindingNarrative('<run_id>', '<finding_id>', {});
console.log(result);

Credentials

Authorization

Sent as a Bearer token. Stored only in your browser.

Response · 200

{
  "data": {
    "id": "string",
    "run_id": "string",
    "detector": "string",
    "severity": "string",
    "entity_type": "string",
    "impact_score": 0,
    "metric_delta": "string",
    "page_path": "string",
    "page_url": "string",
    "query_text": "string",
    "evidence_json": {},
    "narrative": "string",
    "narrative_confidence": "string",
    "narrative_source": "string",
    "narrative_author": "string",
    "created_at": "string"
  }
}