Estimate Fix It Everywhere

POST /v2/agents/fix-it-everywhere/estimate

Estimate Fix It Everywhere

cURL

curl --request POST \
  --url https://api.velt.dev/v2/agents/fix-it-everywhere/estimate \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "url": "<string>",
    "urls": [
      "<string>"
    ],
    "userContext": {},
    "maxPages": 123,
    "organizationId": "<string>"
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Fix It Everywhere estimate computed successfully",
    "data": {
      "estimate": {
        "pagesSampled": 6,
        "pagesWithMatches": 2,
        "matches": 3,
        "estimatedPagesWithMatches": 2
      },
      "pages": {
        "count": 6,
        "source": "list",
        "truncated": false
      }
    }
  }
}

Use this API to estimate how many pages a fix-it-everywhere run would touch before you start it, for a step such as “Found on about 12 pages. Apply everywhere?”. The fix-it-everywhere agent takes one text edit, the text to find and optionally its replacement, and pins the same edit on every other copy of that text across a site.

The body describes the run the way Run Execution does: its site url, its optional page list urls, and its userContext. The estimate reads the first few pages of the list and counts the copies of the search text. Nothing runs, nothing is pinned, and nothing is billed.

Available on V2 only.

​

Endpoint

POST https://api.velt.dev/v2/agents/fix-it-everywhere/estimate

​

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

​

Body

​

Params

data · object · required

Show properties

url · string · required

Valid URL. The site the run reviews. Relative urls entries resolve against it.

urls · string[]

The run’s page list: max 500 entries, each an absolute http(s) URL or a site-relative path. Normalized and checked against the site exactly as a Run Execution page list is, with userContext.sourcePageUrl placed first.

Without urls, the site’s sitemap is read, with sourcePageUrl first. Without a sitemap, only sourcePageUrl and url are read, and the estimate is not extended to the rest of the site.

userContext · object · required

The userContext of the run. It is checked with the run’s own rule, so a search the run would refuse is refused here with the same message. The estimate uses these keys:

Key	Type	Required	Description
findText	string	yes	The text to look for. 2 to 200 characters, and not only stop words. In comment mode it also needs at least 2 words or 8 characters, and cannot be a phrase nearly every page carries, such as “Learn more”.
replaceWith	string	no	The new text, up to 500 characters. Copies that already read it are not counted.
editMode	string	no	"replace", "delete", or "comment". Default: "replace" when there is a replaceWith, "comment" otherwise.
matchCase	boolean	no	Match the case of findText exactly. Default: true.
sourcePageUrl	string	no	The page the edit came from. It is read first.
sourceText	string	no	The text the reviewer selected on sourcePageUrl. When set, one copy on that page is the reviewer’s own and is not counted.

Any other key the run reads is checked the same way, so a value of the wrong type returns INVALID_ARGUMENT.

maxPages · number

Pages to read. Whole number, 1 to 20. Default: 8.

organizationId · string

Accepted and not used.

The schema uses .strict(): unknown fields are rejected, so do not send the rest of a Run Execution body, such as agentId or documentId.

Pages are read as plain HTML through the same guard that keeps agents on public addresses, a few at a time, within about 6 seconds, plus up to 6 seconds to read the sitemap when there is no urls list. A page that does not answer in time, or answers with something other than HTML, is left out.

​

Example Requests

​

1. Estimate over a page list

{
  "data": {
    "url": "https://www.example.com",
    "urls": ["/", "/services", "/about", "/team", "/contact", "/faq"],
    "userContext": {
      "findText": "BOTOX",
      "replaceWith": "Botox",
      "sourcePageUrl": "https://www.example.com/services",
      "sourceText": "BOTOX"
    }
  }
}

​

2. Estimate from the site’s sitemap

{
  "data": {
    "url": "https://www.example.com",
    "userContext": {
      "findText": "Call us today for a free consultation",
      "sourcePageUrl": "https://www.example.com/pricing"
    },
    "maxPages": 12
  }
}

​

Response

​

Success Response

{
  "result": {
    "status": "success",
    "message": "Fix It Everywhere estimate computed successfully",
    "data": {
      "estimate": {
        "pagesSampled": 8,
        "pagesWithMatches": 3,
        "matches": 5,
        "estimatedPagesWithMatches": 13
      },
      "pages": {
        "count": 42,
        "source": "sitemap",
        "truncated": false
      }
    }
  }
}

Field	Type	Description
data.estimate	object | null	The estimate. null when no page could be read.
data.estimate.pagesSampled	number	Pages read.
data.estimate.pagesWithMatches	number	Pages read that have at least one copy the run would change.
data.estimate.matches	number	Copies on the pages read, the reviewer’s own copy left out.
data.estimate.estimatedPagesWithMatches	number | undefined	Pages of the whole list expected to have a copy: the share seen on the pages read, sourcePageUrl left out, applied to the rest of the list. Equal to pagesWithMatches when every page was read. Absent when the length of the list is unknown (pages.source: "none").
data.pages.count	number	Pages the run would review.
data.pages.source	string	Where the page list came from: "list" (your urls), "sitemap", or "none" (no list and no sitemap: sourcePageUrl and url only).
data.pages.truncated	boolean	true when the sitemap listed more pages than a run takes (500).

This is an estimate, not a preview of the run. The pages are read as static HTML rather than rendered, so text a script writes is missed, and a hidden copy, such as a phone menu’s duplicate, is counted even though the run skips it. The run does its own matching on the rendered pages.

​

Failure Response

{
  "error": {
    "message": "userContext.findText is too common to look for on every page. Use a longer, more specific phrase.",
    "status": "INVALID_ARGUMENT"
  }
}

Errors: INVALID_ARGUMENT for:

• a body outside the schema: an invalid url (A valid URL is required), more than 500 urls, maxPages outside 1..20, a missing userContext, or an unknown field;
• a search the run would refuse: userContext.findText is required: the text to look for on every page., userContext.findText must be 2 to 200 characters., userContext.findText is too common to look for on every page. Use a longer, more specific phrase., or A Fix It Everywhere userContext field has the wrong type: <key>;
• a urls list with no page on the site (No usable pages in the list: every entry was blank, off-site or invalid.).

{
  "result": {
    "status": "success",
    "message": "Fix It Everywhere estimate computed successfully",
    "data": {
      "estimate": {
        "pagesSampled": 6,
        "pagesWithMatches": 2,
        "matches": 3,
        "estimatedPagesWithMatches": 2
      },
      "pages": {
        "count": 6,
        "source": "list",
        "truncated": false
      }
    }
  }
}