--- title: "Write one or two sentences that add a fact of the analysis to the guide text" method: POST path: "/api/v1/information-gain/insert" tags: ["v1", "In-guide features"] --- # Write one or two sentences that add a fact of the analysis to the guide text `POST /api/v1/information-gain/insert` ## Request - Base URL: `https://app.serpmantics.com` (the document declares no server; this is the origin it was published from) - URL: `https://app.serpmantics.com/api/v1/information-gain/insert` - Auth: HTTP bearer Réservé : en test, accès sur invitation. Reserved feature, in test, access by invitation. Accounts without access receive 403 FEATURE_NOT_AVAILABLE. Writes one or two sentences, in the tone and language of the text, that bring a fact (kind fact, a missing or partial fact of the consensus) or a lead (kind lead, an information given by a single site) of the latest analysis into the guide text. Nothing is written into the guide, the caller inserts the returned paragraph itself, after the block whose text is anchor (at the end of the text when anchor is null). Competitor brands, site names and prices are generalized. An information specific to one site, with nothing general to draw from it, is refused (422 NOT_TRANSFERABLE, tokens given back). statement must be the exact statement of a fact or lead of the latest analysis, as returned by get_information_gain. htmlContent is optional. When given, the anchor is chosen in this HTML (send the text as displayed, without mark tags); when omitted, the text saved in the guide is used. Synchronous, a few seconds. Costs 3 tokens, charged before the sentences are written (200, the body carries tokensCharged). Nothing is charged when the call is refused before (invalid input, 403, 404, or 409 read before charging). When the writing fails after the charge, whatever the status, the tokens are given back before the response and the body carries refunded (true when the credit is on the ledger, false when the refund failed and is logged for a manual replay). Send an Idempotency-Key header to retry safely after a timeout or a lost connection. With the same key and the same guideId, kind and statement, a call that succeeded (200) in the last 24 hours is answered again as is, with the header Idempotent-Replayed true, without charging nor writing again (tokensCharged keeps the value of the original charge). A call still in progress gives 409 REQUEST_IN_PROGRESS, another guideId, kind or statement gives 422 IDEMPOTENCY_KEY_REUSED, and a call that failed frees the key (nothing was charged, the retry is processed as a new call). Keys are scoped to the account. ## Headers - `Idempotency-Key` string ## Request body - object - `guideId` string, required: ID of the guide (24 hexadecimal characters). - `kind` 'fact' | 'lead', required: fact for a missing or partial fact of the consensus, lead for an information given by a single site. - `statement` string, required: Exact statement of the fact or lead, as returned by get_information_gain. At most 300 characters (Unicode code points). - `htmlContent` string: Optional HTML of the article, without mark tags. Omit it to use the text saved in the guide. At most 2,000,000 bytes (UTF-8). ## Response `200` Sentences written. Insert html after the block whose text is anchor. - object - `success` boolean - `data` object - `html` string: The sentences, HTML-escaped, in one p element. - `text` string: The same sentences, as plain text. - `mode` 'after': Always after, the paragraph is added and never replaces text. - `anchor` string, nullable: Text of the block after which to insert (one whole line of the text, one line per heading, paragraph, list item or cell), null to insert at the end of the text. - `block` integer, nullable: Rank of that line among the non-empty lines of the text, from 1, to tell apart two blocks with the same text. null when anchor is null. - `tokensCharged` integer: Tokens charged for this call. ## Other responses - `400`: Invalid input, or not enough tokens. code is INVALID_GUIDE_ID, INVALID_KIND, INVALID_STATEMENT, INVALID_HTML_CONTENT or INVALID_IDEMPOTENCY_KEY, fix the input and do not retry as is. code INSUFFICIENT_TOKENS means the balance is under the 3 tokens of a suggestion, nothing was charged, and the body carries inviteToUpgrade true, upgradeType tokens and tokensRequired. code TOKENS_NOT_CONSUMED means the debit could not be confirmed, nothing was written. - `401`: Unauthorized, invalid or missing API key. - `403`: code FEATURE_NOT_AVAILABLE. The feature is in test and reserved to invited accounts. Nothing was read nor charged. Do not retry. - `404`: code GUIDE_NOT_FOUND (guide unknown, deleted or not accessible, deliberately indistinguishable), NO_ANALYSIS (launch an analysis first) or FACT_NOT_FOUND (the statement is not in the latest analysis, read it again). - `405`: Method not allowed. - `409`: code ANALYSIS_RUNNING (an analysis or a recheck is running, wait until it is done) or ANALYSIS_NOT_DONE (the latest analysis failed, launch a new one). Nothing is charged when the conflict is read before charging; otherwise the tokens are given back and the body carries refunded. code REQUEST_IN_PROGRESS means a call with the same Idempotency-Key is still running, nothing more was charged, retry in a moment with the same key. - `413`: code CONTENT_TOO_LARGE. htmlContent (or the saved text) is over 2,000,000 bytes (UTF-8). A JSON body over 4 MB is refused before being read, with a plain text 413. - `422`: code NOT_TRANSFERABLE. The information is specific to one competitor site (its own price, catalogue, address), there is nothing general to add from it. The tokens charged for the call are given back and the body carries refunded. Do not retry with the same statement. code IDEMPOTENCY_KEY_REUSED means the Idempotency-Key was already used for another guideId, kind or statement in the last 24 hours, nothing was charged, send a new key. - `500`: Internal error. When the token debit could not be recorded, the tokens are given back and the body carries refunded. - `502`: code BACKEND_ERROR. The analysis service did not answer, or no model could write a valid suggestion. Retry later. The tokens charged for the call are given back and the body carries refunded. - `503`: Temporary outage (database or analysis service). Retry after a short delay. code BACKEND_SLOW means the reads before writing took too long to leave time for the writing: nothing was charged. --- [API](https://skmtc.dev/serpmantics/apis/api-serpmantics.md) · [All operations](https://skmtc.dev/serpmantics/apis/api-serpmantics/llms.txt) · [OpenAPI document](https://skmtc.dev/serpmantics/apis/api-serpmantics/revisions/e71b28ef35a8?raw)