v1
In-guide features

Write one or two sentences that add a fact of the analysis to the guide text

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.

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

Headers

Idempotency-Keystring
Example:5f0c6a7e-2b1d-4f7a-9c1e-3d2b8a6f4e10

Optional. 1 to 255 printable ASCII characters, without spaces (a UUID is a good choice). Use a new key for each new suggestion, and the same key to retry the same one. Invalid value gives 400 INVALID_IDEMPOTENCY_KEY, nothing charged.

Request body

guideIdstring 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.

statementstring required

Exact statement of the fact or lead, as returned by get_information_gain. At most 300 characters (Unicode code points).

htmlContentstring

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).

Example request

{
  "guideId": "507f1f77bcf86cd799439011"
}

Response

Sentences written. Insert html after the block whose text is anchor.

successboolean

Example response

{
  "success": true,
  "data": {
    "block": 4,
    "tokensCharged": 3
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.